Most developer tools start the same way. You need to do a thing repeatedly, so you write a script. The script grows flags. The flags grow subcommands. Before you know it, you've got a CLI.
\nWe had this exact experience when building an internal platform tool to help our solutions team ship faster. It scaffolds projects, spins up dev environments, generates configs, and deploys to staging.
\nAs our CLI grew in scope, so did the number of our internal users. But then, something interesting happened: suddenly, we were no longer building just for human developers, but for coding agents too.
\nBefore we talk about agents, let's talk about what makes a CLI actually pleasant for human developers.
\nSpaces is opinionated about the boring stuff. It picks sane directory structures so you don't have to. It generates the config files you'd otherwise copy from the last project. It wires services together so your API and your frontend can talk on day one, not after an hour of YAML editing or “vibing”.
\nHere's what a typical session looks like:
\n$ spaces init my-project$ cd my-project$ spaces dev\nThree commands. You go from nothing to a running multi-service project with hot reload, a database, and generated Dockerfiles. That's the bar.
\nThe commands that matter tend to fall into three buckets:
\nScaffolding -- These create structure, ask questions, show options, let you explore.
\nDevelopment -- These are your inner loop. They just “run”.
\nOperations -- These touch production. Careful, double-check before acting
\nThis is all table stakes. But then our second user showed up and we discovered we needed something a little different, and a lot more interesting.
\nWe built a TUI module picker for init. Fancy changes, commands, it looked super.
Then an agent tried to use it.
\nThe agent saw raw ANSI escape codes. \\\\\\\\x1b[36m?\\\\\\\\x1b[0m Select components. It couldn't send arrow keys or toggle selections. It was locked out of the command entirely.
The fix seems obvious in retrospect: add a --components flag. But the real insight was bigger than one flag.
Every time your CLI asks an interactive question, there's an implicit contract: "I need this piece of information to proceed." To fulfill that contract, you can use an interactive prompt. Or you can use a flag or config file.
\nThe trick is to think about the information first and the input method second.
\n = : = = \n # Same logic from here create_project(selected)\nThree input paths, one execution path. The business logic doesn't know how the inputs arrived. This means you test it once, not three times.
\nThe -y flag deserves special attention. It's not just "skip confirmations." It's a contract that says: I'm providing everything you need programmatically, don't block on stdin. When you run with -y, every prompt resolves to either a flag value or a smart default. If it can't, it fails loudly instead of hanging.
Example in practice: the interactive elements in this post.
\nThe elements were built in a fresh repository. An agent was retroactively asked to wire the project into [spaces cli] for deployment. It started by running --help across the relevant commands to understand the interface. From that, it figured out which configuration files were needed, generated a config.yaml, and connected the Dockerfile and registry settings - no hand-holding required.
In the same pass, it set up the GitHub Actions CI pipeline. From a single prompt to a live deployment took under 10 minutes (a cycle time we're actively working to bring down). After that, the repository was fully configured and the embeds were deployed with Koyeb — as a Space, scaffolded and deployed through Spaces itself. Yes, the interactive demos embedded in this blog post about Spaces are running as a Space. Spaception.
\nBecause every interactive input had a flag equivalent, the agent could operate autonomously end-to-end.
\nThe CLI our team was building helped our applied AI engineers ship apps. But not every app looks the same. Some need a backend and a vector database. Others just need a relational database, a frontend, and some APIs. A few are worker-only services with no UI at all.
\nWe were not about to hardcode the module types. So we built a plugin system where each component is a plugin that declares its own properties:
\n : : : \n ... -> : ...\nPlugins are introspectable. You can list them, serialize them, diff them. A human browses a TUI picker. An agent queries the registry and gets JSON back. Same data, different rendering.
\nThis accidentally solved a problem we didn't know we had. Before, adding a new module type meant updating the picker, the Dockerfile generator, the env file writer, and the compose template. Now it means writing one plugin class. The registry is the single source of truth and everything reads from it.
\n\n\n\n\nThere's an old saying that content is king. With agents, context is.
\n
The most impactful thing we did for agent usability was generating two files on every init:
context.json -- a structured snapshot of the project: what modules exist, ports they use, commands to run, env vars they need.
AGENTS.md -- a set of rules written for LLMs and more imperative than your regular one. Not "this project uses PostgreSQL" but "run mycli dev --migrate before testing database changes."
An agent that reads these files before acting makes dramatically fewer mistakes. Basically, it won’t guess at port numbers, run the wrong test command, try to install dependencies that are already managed by the toolchain.
\nThe context file also acts as a cache-buster for stale agent assumptions. When you add a module or change a deploy target, the context file updates automatically on the next dev or init. The agent reads fresh state every time.
The subtlest problem we hit was implicit state. Our add command read config.yaml from the current working directory. A human cds to the right folder without thinking. An agent running commands from a workspace root has no idea it needs to be in a subdirectory.
The fix:
\n# Before: CWD dependencyconfig = load_config(Path.cwd() / "config.yaml")\n# After: explicit with fallbackconfig = load_config( path or find_config_in_parents(Path.cwd()))\nEvery hidden assumption -- CWD, environment variables, dotfiles in $HOME -- is a place where an agent will trip. Explicit parameters with sensible fallbacks solve it for agents and make scripting easier for humans too.
Looking back, the changes were small individually. Just a set of principles applied consistently:
\nEvery interactive input has a flag equivalent
\nEvery flag has a smart default for headless mode
\nState is explicit. CWD, env vars, and config paths are inputs, not assumptions
\nPlugins are data models, not just code. Introspectable by default
\nContext files give agents (and CI, and scripts) a structured description of the project
\nThe funny part is that none of this made the CLI worse for humans. The TUI picker still works and looks fancy, progress spinners still spin, confirmation dialogs still confirm. We just added a second door.
\nAnd that second door turned out to be the more important one. Not because agents matter more than humans, but because the constraints they impose are the same constraints that make a CLI composable, scriptable, and testable. Designing for agents forced us to build a better tool for everyone.
\nIf you're building developer tools right now, you don't need a separate agent API. You need to look at every input() call, every CWD assumption, every pretty-printed-only output, and ask: what if the user on the other end is a process, not a person?
The answer to that question will improve your tool either way.
\nSpaces CLI is built by Lorenzo Signoretti, Riwa Hoteit & Sam Fenwick at Mistral AI. Special thanks to our Applied AI team, the earliest and most demanding users of the CLI, whose real-world usage shaped every pattern described here. We're excited to see the applications it will help them build with our Customers to solve painful use cases.
\nThe tooling layer between humans and agents is still being figured out. If building developer tools at the intersection of AI and infrastructure sounds like your thing, we’re hiring.
\n", "content_markdown": "Most developer tools start the same way. You need to do a thing repeatedly, so you write a script. The script grows flags. The flags grow subcommands. Before you know it, you've got a CLI.\n\nWe had this exact experience when building an internal platform tool to help our solutions team ship faster. It scaffolds projects, spins up dev environments, generates configs, and deploys to staging.\n\nAs our CLI grew in scope, so did the number of our internal users. But then, something interesting happened: suddenly, we were no longer building just for human developers, but for coding agents too.\n\n## What Good DX Looks Like\n\nBefore we talk about agents, let's talk about what makes a CLI actually pleasant for human developers.\n\nSpaces is opinionated about the boring stuff. It picks sane directory structures so you don't have to. It generates the config files you'd otherwise copy from the last project. It wires services together so your API and your frontend can talk on day one, not after an hour of YAML editing or “vibing”.\n\nHere's what a typical session looks like:\n\n```text\n$ spaces init my-project$ cd my-project$ spaces dev\n```\n\nThree commands. You go from nothing to a running multi-service project with hot reload, a database, and generated Dockerfiles. That's the bar.\n\nThe commands that matter tend to fall into three buckets:\n\n- **Scaffolding** -- These create structure, ask questions, show options, let you explore.\n\n- **Development** -- These are your inner loop. They just “run”.\n\n- **Operations** -- These touch production. Careful, double-check before acting\n\nThis is all table stakes. But then our second user showed up and we discovered we needed something a little different, and a lot more interesting.\n\n## The Second User: The Agent\n\nWe built a TUI module picker for `init`. Fancy changes, commands, it looked super.\n\nThen an agent tried to use it.\n\nThe agent saw raw ANSI escape codes. `\\\\\\\\x1b[36m?\\\\\\\\x1b[0m Select components`. It couldn't send arrow keys or toggle selections. It was locked out of the command entirely.\n\nThe fix seems obvious in retrospect: add a `--components` flag. But the real insight was bigger than one flag.\n\n## Every prompt is a flag in disguise\n\nEvery time your CLI asks an interactive question, there's an implicit contract: \"I need this piece of information to proceed.\" To fulfill that contract, you can use an interactive prompt. Or you can use a flag or config file.\n\nThe trick is to think about the *information* first and the *input method* second.\n\n```python\ndef init_command( components: str | None = Option(None), yes: bool = Option(False, \"-y\"),): if components: selected = components.split(\",\") elif yes: selected = get_defaults() else: selected = show_picker()\n # Same logic from here create_project(selected)\n```\n\nThree input paths, one execution path. The business logic doesn't know how the inputs arrived. This means you test it once, not three times.\n\nThe `-y` flag deserves special attention. It's not just \"skip confirmations.\" It's a contract that says: *I'm providing everything you need programmatically, don't block on stdin.* When you run with `-y`, every prompt resolves to either a flag value or a smart default. If it can't, it fails loudly instead of hanging.\n\n**Example in practice: the interactive elements in this post.**\n\nThe elements were built in a fresh repository. An agent was retroactively asked to wire the project into \\[spaces cli\\] for deployment. It started by running `--help` across the relevant commands to understand the interface. From that, it figured out which configuration files were needed, generated a `config.yaml`, and connected the Dockerfile and registry settings - no hand-holding required.\n\nIn the same pass, it set up the GitHub Actions CI pipeline. From a single prompt to a live deployment took under 10 minutes (a cycle time we're actively working to bring down). After that, the repository was fully configured and the embeds were [deployed](https://spaces-blogs-staging-mistral-01d83c8e.koyeb.app/) with [Koyeb](https://www.koyeb.com/) — as a Space, scaffolded and deployed through Spaces itself. Yes, the interactive demos embedded in this blog post about Spaces are running as a Space. *Spaception*.\n\nBecause every interactive input had a flag equivalent, the agent could operate autonomously end-to-end.\n\n## Structured Data as Interface\n\nThe CLI our team was building helped our applied AI engineers ship apps. But not every app looks the same. Some need a backend and a vector database. Others just need a relational database, a frontend, and some APIs. A few are worker-only services with no UI at all.\n\nWe were not about to hardcode the module types. So we built a plugin system where each component is a plugin that declares its own properties:\n\n```python\nclass ModulePlugin(BaseModel): type_id: str category: str default_port: int\n def get_env_vars(self) -> list[EnvVarDef]: ... def get_dev_command(self, port: int) -> str: ...\n```\n\nPlugins are introspectable. You can list them, serialize them, diff them. A human browses a TUI picker. An agent queries the registry and gets JSON back. Same data, different rendering.\n\nThis accidentally solved a problem we didn't know we had. Before, adding a new module type meant updating the picker, the Dockerfile generator, the env file writer, and the compose template. Now it means writing one plugin class. The registry is the single source of truth and everything reads from it.\n\n## Teaching Agents About Your Project\n\n> > There's an old saying that content is king. With agents, context is.\n\nThe most impactful thing we did for agent usability was generating two files on every `init`:\n\n`context.json` -- a structured snapshot of the project: what modules exist, ports they use, commands to run, env vars they need.\n\n`AGENTS.md` -- a set of rules written for LLMs and more imperative than your regular one. Not \"this project uses PostgreSQL\" but \"run `mycli dev --migrate` before testing database changes.\"\n\nAn agent that reads these files before acting makes dramatically fewer mistakes. Basically, it won’t guess at port numbers, run the wrong test command, try to install dependencies that are already managed by the toolchain.\n\nThe context file also acts as a cache-buster for stale agent assumptions. When you add a module or change a deploy target, the context file updates automatically on the next `dev` or `init`. The agent reads fresh state every time.\n\n## Implicit State is the Enemy\n\nThe subtlest problem we hit was implicit state. Our `add` command read `config.yaml` from the current working directory. A human `cd`s to the right folder without thinking. An agent running commands from a workspace root has no idea it needs to be in a subdirectory.\n\nThe fix:\n\n```python\n# Before: CWD dependencyconfig = load_config(Path.cwd() / \"config.yaml\")\n# After: explicit with fallbackconfig = load_config( path or find_config_in_parents(Path.cwd()))\n```\n\nEvery hidden assumption -- CWD, environment variables, dotfiles in `$HOME` -- is a place where an agent will trip. Explicit parameters with sensible fallbacks solve it for agents and make scripting easier for humans too.\n\n## The Checklist\n\nLooking back, the changes were small individually. Just a set of principles applied consistently:\n\n- Every interactive input has a flag equivalent\n\n- Every flag has a smart default for headless mode\n\n- State is explicit. CWD, env vars, and config paths are inputs, not assumptions\n\n- Plugins are data models, not just code. Introspectable by default\n\n- Context files give agents (and CI, and scripts) a structured description of the project\n\n## Building a Better Tool for Everyone\n\nThe funny part is that none of this made the CLI worse for humans. The TUI picker still works and looks fancy, progress spinners still spin, confirmation dialogs still confirm. We just added a second door.\n\nAnd that second door turned out to be the more important one. Not because agents matter more than humans, but because the constraints they impose are the same constraints that make a CLI composable, scriptable, and testable. Designing for agents forced us to build a better tool for everyone.\n\nIf you're building developer tools right now, you don't need a separate agent API. You need to look at every `input()` call, every CWD assumption, every pretty-printed-only output, and ask: what if the user on the other end is a process, not a person?\n\nThe answer to that question will improve your tool either way.\n\nSpaces CLI is built by Lorenzo Signoretti, Riwa Hoteit & Sam Fenwick at Mistral AI. Special thanks to our Applied AI team, the earliest and most demanding users of the CLI, whose real-world usage shaped every pattern described here. We're excited to see the applications it will help them build with our Customers to solve painful use cases.\n\n**The tooling layer between humans and agents is still being figured out. If building developer tools at the intersection of AI and infrastructure sounds like your thing,** [**we’re hiring**](https://mistral.ai/careers)**.**\n", "dateCreated": "2026-10-19T01:26:53.998049939+00:00", "date_created": "2026-03-31T12:00:00+00:00", "date_modified": "2026-03-31T12:00:00+00:00", "date_published": "2026-03-31T12:00:00+00:00", "description": "Most developer tools start the same way. You need to do a thing repeatedly, so you write a script. The script grows flags. The flags grow subcommands. Before you know it, you've got a CLI. We had this exact experience when building an…", "external_url": "https://mistral.ai/news/spaces/", "git": { "commit": "ebb0941c5c06a2ab2377342d607535262a3e969e", "path": "items/mistral-ai/2026/03/2026-03-31-spaces-a-cli-built-for-humans-and-agents.md", "permalink": "https://github.com/aymericbeaumet/aggr-instance/blob/ebb0941c5c06a2ab2377342d607535262a3e969e/items/mistral-ai/2026/03/2026-03-31-spaces-a-cli-built-for-humans-and-agents.md" }, "id": "urn:aggr:item:8930f8048a4ec3ce0dca73332cba17c0438480be", "isBasedOn": { "@id": "https://mistral.ai/news/spaces/" }, "mainEntity": { "@id": "https://mistral.ai/news/spaces/", "@type": "CreativeWork", "archivedAt": { "@id": "https://aggr.aymericbeaumet.com/items/mistral-ai/2026-03-31-spaces-a-cli-built-for-humans-and-agents/#webpage" }, "dateModified": "2026-03-31T12:00:00+00:00", "datePublished": "2026-03-31T12:00:00+00:00", "headline": "Spaces: A CLI Built for Humans and Agents", "image": { "@type": "ImageObject", "caption": null, "height": 90, "url": "https://mistral.ai/cms-media/api/media/file/thumbnail-03.jpg", "width": 160 }, "timeRequired": "PT7M", "url": "https://mistral.ai/news/spaces/", "wordCount": 1418 }, "name": "Archived snapshot: Spaces: A CLI Built for Humans and Agents", "preview": { "alt": null, "color": null, "height": 90, "placeholder": { "data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=", "hash": "" }, "url": "https://mistral.ai/cms-media/api/media/file/thumbnail-03.jpg", "width": 160 }, "reading_minutes": 7, "replicated_at": null, "source": "mistral-ai", "source_name": "Mistral Blog", "summary": null, "tags": [], "temporalCoverage": "2026-10-19T01:26:53.998049939+00:00", "title": "Spaces: A CLI Built for Humans and Agents", "url": "https://aggr.aymericbeaumet.com/items/mistral-ai/2026-03-31-spaces-a-cli-built-for-humans-and-agents/", "word_count": 1418 }