Spaces CLI built for humans and agents

TL;DR

Mistral AI released Spaces, a command‑line interface that lets developers create, run, and deploy multi‑service projects with just three commands, and it is engineered so every interactive prompt has a flag or config equivalent, enabling autonomous AI agents to use the tool without manual intervention.

What Makes a Good Developer Experience

Spaces focuses on eliminating repetitive setup work. It chooses sensible directory layouts, auto‑generates configuration files, and wires services together so that a new project is runnable with hot‑reload, a database, and Dockerfiles after running:

$ spaces init my-project
$ cd my-project
$ spaces dev

The CLI groups commands into three functional buckets:

  • Scaffolding – creates project structure, asks questions, and shows options.
  • Development – runs the inner development loop with a single spaces dev command.
  • Operations – performs production‑level actions that require explicit confirmation.

Designing for the Second User: AI Agents

When an AI coding agent attempted to use the interactive TUI picker for init, it encountered raw ANSI escape codes and could not navigate the UI. The simple fix was to expose a --components flag, but the deeper insight was that every piece of information requested by a CLI should have a non‑interactive representation.

Flags as Universal Contracts

Each interactive question represents a contract: the CLI needs a value to continue. By providing a flag, a config file, or a default, the same business logic runs regardless of how the input arrives. Example implementation:

def 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()
    create_project(selected)

The -y flag signals that the caller supplies all required data programmatically, causing the CLI to fail loudly if any required input is missing instead of hanging on stdin.

End‑to‑End Agent Workflow

An agent can now:

  1. Run spaces --help to discover command signatures.
  2. Generate a config.yaml and context.json automatically.
  3. Wire Dockerfiles, registry settings, and CI pipelines without human interaction.
  4. Deploy the repository as a Space on Koyeb in under ten minutes.

Because each interactive prompt has a flag equivalent, the agent operates autonomously from start to deployment.

Structured Data as the Interface Layer

Spaces uses a plugin system where each module is described by a data model rather than hard‑coded logic:

class ModulePlugin(BaseModel):
    type_id: str
    category: str
    default_port: int
    def get_env_vars(self) -> list[EnvVarDef]: ...
    def get_dev_command(self, port: int) -> str: ...

Plugins are introspectable, serializable to JSON, and can be diffed. Humans interact via a TUI picker, while agents query the registry and receive JSON. Adding a new module now requires only a new plugin class, eliminating duplicated updates across pickers, Dockerfile generators, and compose templates.

Providing Context for Agents

Spaces generates two files on every init:

  • context.json – a snapshot of the project’s modules, ports, commands, and environment variables.
  • AGENTS.md – explicit procedural instructions for LLMs, e.g., “run mycli dev --migrate before testing database changes.”

These artifacts give agents a reliable source of truth, reducing guesswork and preventing mistakes such as using wrong ports or installing duplicate dependencies. The context file also acts as a cache‑buster; it updates automatically whenever the project configuration changes.

Eliminating Implicit State

Implicit assumptions (e.g., relying on the current working directory) break agent automation. The fix is to make all state explicit with sensible fallbacks:

# Before
config = load_config(Path.cwd() / "config.yaml")
# After
config = load_config(
    path or find_config_in_parents(Path.cwd())
)

Making CWD, environment variables, and dot‑file locations explicit improves both agent reliability and human scripting.

Checklist of Agent‑Friendly Practices

  • Every interactive input has a corresponding flag.
  • Flags provide smart defaults for headless execution.
  • All state (paths, env vars, configs) is passed explicitly.
  • Plugins are pure data models, automatically introspectable.
  • context.json and AGENTS.md give agents a structured project description.

Why This Improves Tools for Everyone

The added agent‑oriented design does not degrade the human experience: the TUI picker, spinners, and confirmation dialogs remain unchanged. Instead, the constraints required for agents (explicit inputs, flag‑based contracts, structured metadata) also make the CLI more composable, scriptable, and testable for developers.

Mistral AI recommends that any developer‑tool creator audit every input() call, CWD assumption, and human‑only output, and ask whether a non‑human process could use the same interface. Addressing those questions yields a more robust tool for both humans and agents.

Spaces CLI was built by Lorenzo Signoretti, Riwa Hoteit, and Sam Fenwick at Mistral AI, with feedback from the Applied AI team.

Sources