CLI reference
The agents command creates an agent project, runs the agent on your machine, deploys it to
Mistral, and talks to it from the terminal. The guides show each command in use:
Quickstart, Self-hosted (agents serve),
Mistral-managed (agents deploy) and Agent lifecycle.
The agents command comes with the mistralai-agents package: see
Install without agents init.
Commands
| I want to | Command |
|---|---|
| Create a project ready to deploy | agents init NAME |
| See what the CLI loads from my project | agents info [PATH] |
| Run the agent on my machine, self-hosted | agents serve [PATH] |
| Deploy the agent, Mistral-managed | agents deploy [PATH] |
| See my workspace's agents | agents list |
| Read a deployed agent's logs | agents logs NAME |
| Talk to an agent | agents chat [NAME] |
| Shut an agent down for good | agents shutdown NAME |
| Install a skill for my coding agent | agents skills add NAME |
A project goes through four steps:
agents init my-agentcreates it.agents infoshows what the CLI loads from it.agents serveruns it on your machine, andagents chat my-agenttalks to it.agents deploydeploys it to Mistral.
agents info, agents serve and agents deploy take a project root, . by default. In it they
look for agent in main.py, or the module:attr in pyproject.toml:
[tool.mistralai.agents]
entrypoint = "src.service:support_agent"The agent must set name=. See Self-hosted (agents serve).
Global options
agents [OPTIONS] COMMAND [ARGS]...| Option | What it does |
|---|---|
--version | Prints the installed version, such as mistralai-agents 1.1.0, and exits. |
--install-completion | Installs completion for the current shell. |
--show-completion | Prints the completion script for the current shell, to copy or customize it. |
--help | Prints the help and exits. Every command takes it too. |
With no command, agents prints the help and exits with status 2.
agents init
agents init [OPTIONS] [NAME]Creates a new agent project in a folder named NAME, ready for agents deploy. It locks the
project's dependencies with uv, then asks for your API key and writes it to .env.
| Argument or option | What it does |
|---|---|
NAME | The agent's name, and the project's folder. |
--name NAME | The same, as an option. Two different names are an error. |
--yes, -y | Installs uv if it is missing, asks no API key and writes an empty .env, and commits the project in a new git repository. It still asks for a name you did not give, when a terminal is there. |
--no-git | Creates no git repository. |
--exempt-from-exclude-newer | Exempts the SDK from your uv exclude-newer cutoff, which would hide a recent release. |
With no name and no terminal to ask in, it stops with No agent name was given. Run `agents init NAME`.
More in Quickstart.
agents info
agents info [PATH]Prints the agent the CLI loads from the project at PATH: its model, instructions, tools,
connectors, MCPs, skills, guardrails, hooks, subagents and permissions. For a main.py with one
tool:
When its checks find a problem, it lists them under checks: ✗ for an error, ⚠ for a
warning. It names the first thing it could not load, and exits with status 1 when it finds no agent
or a check finds an error. More in
Self-hosted (agents serve).
agents serve
agents serve [OPTIONS] [PATH]Runs the agent on your machine, registers it in your workspace, and prints a link to trigger it. Ctrl+C stops it.
| Argument or option | What it does |
|---|---|
PATH | The project root. Default: .. |
--name NAME | Registers the agent under this name instead of the one in its code. |
--send-config / --no-send-config | Sends the agent's configuration to Mistral, as agents deploy does, so it shows with the agent and its sessions in your workspace. A restart with the same configuration and code version stores no new copy of it. Default: --send-config; --no-send-config registers the agent without it. Environment: AGENTS_SDK_SERVE_SEND_CONFIG. |
It prints only warnings and the banner; AGENTS_SDK_DEBUG=1 prints its full logs. More in
Self-hosted (agents serve).
agents deploy
agents deploy [OPTIONS] [PATH]Builds the project into an image and deploys it to Mistral, in your workspace. Deploying a name again replaces the agent that has it.
| Argument or option | What it does |
|---|---|
PATH | The project root. Default: .. |
--name NAME | Deploys the agent under this name instead of the one in its code. |
--hardened / --no-hardened | Hardens the deployment, so the agent can use connectors and MCPs on behalf of the user who started the session. Default: hardened when the agent acts on behalf of the session's user. Such an agent needs it: with --no-hardened, its deployment does not start. |
--dockerfile PATH | The Dockerfile to build, relative to the project. Default: Dockerfile. |
--secret-binding ENV_VAR=secret:workspace:NAME | Binds a workspace secret to an environment variable of the deployed agent. Pass the reference, never the secret's value. Repeat it for each variable. It is the complete set: a deploy without it unbinds the secrets a previous deploy bound. |
--yes, -y | Writes a missing Dockerfile and .python-version without asking. |
Ctrl+C while it waits for the deployment stops the wait, not the deploy: the agent keeps deploying,
and agents deploy exits with status 130. More in
Mistral-managed (agents deploy): your own Dockerfile, secrets and tracing.
agents list
agents listLists your workspace's agents, how each one runs, and whether it is running. It takes no options.
not observed means Mistral saw nothing running the agent: it is stopped, or its status could not
be read. More in Agent lifecycle.
agents logs
agents logs [OPTIONS] NAMEPrints the latest lines of a deployed agent's logs. A served agent's logs are in the terminal that
runs agents serve.
| Argument or option | What it does |
|---|---|
NAME | The deployed agent. Required. |
--follow, -f | Keeps printing new lines as they are written. |
--lines N, -n N | How many of the latest lines to print first, from 1 to 1000. Default: 100. |
--timestamps, -t | Prefixes each line with its time. |
--level LEVEL, -l LEVEL | Prints only lines at this level or above: debug, info, warning or error. Indented lines under a kept line, such as a traceback, are kept too. |
--json | Prints one JSON object per line, with time, stream, level, logger, message and fields. |
More in Agent lifecycle.
agents chat
agents chat [OPTIONS] [NAME]Talks to an agent from the terminal. With NAME, it talks to the agent of that name, self-hosted or
Mistral-managed. Without it, it runs the project's agent in this process, and registers nothing.
| Argument or option | What it does |
|---|---|
NAME | The agent to talk to, self-hosted or Mistral-managed. Omit it to run the project's agent in this process. |
--path PATH | The project root, when you omit NAME. Default: .. |
--message TEXT, -m TEXT | Sends this one message, prints the reply and exits. The exit status is 1 when the turn did not complete. |
During a turn, Ctrl+C interrupts it and keeps the chat open. At the prompt, Ctrl+C, Ctrl+D, /exit
or /quit ends the chat. Under
permission_mode="ask", the chat asks before each tool call: y allows it once, a allows it for
the rest of the session, n denies it. A hook's approval offers only y and n. agents chat refuses a client tool call at once, and the
turn continues. More in
Agent lifecycle.
agents shutdown
agents shutdown [OPTIONS] NAMEShuts an agent down for good. NAME is the agent's deployed name, which --name may have changed.
| Argument or option | What it does |
|---|---|
NAME | The agent to shut down. Required. |
--yes, -y | Skips the confirmation prompt. |
More in Agent lifecycle.
agents skills add
agents skills add NAMEInstalls a skill the SDK ships into .agents/skills/ in the current folder, for your coding agent:
run it at the root of your project. migrate-1.1 migrates a project from a 1.1 release candidate
to 1.1. Running it again replaces the installed files with the
ones of the installed SDK.
migrate-1.1 also migrates a project from Agents SDK 1.0.7.
| Argument | What it does |
|---|---|
NAME | The skill to install: migrate-1.1. |
uvx --python 3.12 --from mistralai-agents agents skills add migrate-1.1--python 3.12 keeps uvx off the free-threaded Python 3.14t, where the install fails.
Exit status
| Status | Meaning |
|---|---|
| 0 | Success, or Ctrl+C on agents serve or agents logs --follow. |
| 1 | The command failed, and printed why. agents chat also exits 1 when it loses the connection to the session. |
| 2 | A usage error: an unknown option, a missing argument, a value out of range. |
| 130 | agents deploy stopped waiting on Ctrl+C; the deploy keeps running in the background. |
Environment
| Variable | Read by | What it sets |
|---|---|---|
MISTRAL_API_KEY | every command that calls the API | Your API key. |
MISTRAL_API_URL | every command that calls the API | The API root, without /v1. |
AGENTS_SDK_SERVE_SEND_CONFIG | agents serve | The default of --send-config. |
AGENTS_SDK_CODE_VERSION | agents serve | The code version: a restart with the same value keeps the agent. Default: a hash of the project. See Agent lifecycle. |
AGENTS_SDK_DEBUG | every command, and any program that imports the SDK | 1 prints the full logs. |
Export the variables in your shell, or load .env with uv run --env-file .env agents ...; a variable your shell exports wins over the file.
Next
- The whole API: every Python call, by what you want to do.