Convex CLI for coding agents

Before changing a Convex backend, a coding agent needs to understand how the project’s functions work and what data it stores. The Convex CLI is a command-line tool for managing Convex projects and deployments. It also inspects data and runs functions, and it generates code. A deployment is a Convex environment, such as development or production, that stores data and runs backend functions.

You can give an agent shell access to the CLI to inspect a development deployment, then ask it to make a focused code change. The CLI also offers a beta Model Context Protocol (MCP) server, a way for AI tools to call Convex-specific tools directly. The standard CLI commands are useful for straightforward shell tasks; the MCP server’s interface is still marked beta in the Convex CLI documentation.

Install and connect a project

From the root of an existing Convex project, install the Convex package:

npm install convex

Then start the development command:

npx convex dev

Convex documents npm install convex as the package installation command. The first development run connects the project to a Convex deployment and may guide you through signing in and choosing or creating a project. The CLI stores the connection for later commands. It watches local Convex files, sends code changes to the development deployment, and updates generated types. The CLI uses the network to send code changes to the selected development deployment and update generated types. This changes the deployment, unlike a data inspection command, which only reads data. See the CLI overview for the command’s role and related project-management commands.

Sign in through the CLI’s authentication flow rather than putting credentials or deployment keys in an agent prompt. If an agent needs its own cloud environment, Convex describes an Agent Mode that can provision a separate development deployment and scope a deploy key to it in its AI coding documentation.

Inspect a table without changing it

A concrete agent task is to inspect a table and report which fields its documents contain. After the project is connected and npx convex dev has selected the intended development deployment, run:

npx convex data tasks

Replace tasks with the table name in your project. The command displays documents from that table in the selected deployment. The fields shown depend on your schema and the rules that define the table’s fields. They also depend on which records exist, so the output varies. This inspection sends a read request to Convex; it does not edit local files or issue a database write.

A suitable prompt for the agent is:

Inspect the tasks table in the selected Convex development deployment using the CLI. Summarize the fields present in its documents and note any inconsistencies. Do not change data or project files.

Before inspecting records, the agent should verify that the project is connected to the development deployment, because the command reads from whichever deployment is selected. Convex also supports inline queries for custom read-only logic. The CLI documentation says these queries run in a sandbox, an environment that cannot modify the database or access the network. In contrast, npx convex run runs a function from the project. What it does depends on that function’s code, so review the function before asking an agent to run it.

Give the agent the right Convex context

Convex provides npx convex ai-files commands to manage AI helper files, including generated guidelines and managed sections in agent instruction files. Convex recommends its plugins for Claude Code, Codex, and Cursor; those plugins include AI rules. For other editors, Convex documents adding a convex_rules.txt file. These instructions give an agent project-specific guidance without requiring it to infer Convex conventions from existing code. The AI coding overview describes these options.

The CLI can also run functions, manage environment variables, import and export data, display logs, and generate code. Before running a command, an agent should check what it does: npx convex dev pushes local code to a development deployment, while a data-inspection command reads deployment data. Convex’s npx convex mcp server is another option for agents that support MCP, but Convex labels it beta, so its interface may change.