cli-conventions

name: cli-conventions description: CLI command patterns, global flags, project bootstrap, and workspace layout for the autopilot CLI. Use when adding commands, subcommands, modifying global flags, creating new workspaces, diagnosing workspace issues, or understanding the project overlay structure.

Entry point

autopilot.cli.main:main, program name autopilot. Implementation uses Command subclasses (forward(), nested commands, @subcommand) composed on AutoPilotCLI; main() calls AutoPilotCLI()().

Top-level commands

Omitting a subcommand where required exits with help or error per argparse rules. Running autopilot with no command prints top-level help and exits 0.

Global flags

Leaf parsers and inline @subcommand parsers pick up shared flags via make_subparser() (invoked from Command.register() in cli/command.py), which calls add_global_flags() in cli/resolvers.py:

--json behavior

When --json is set, Output buffers structured messages. info, success, warn, and error append objects with level and message. data and table append typed records. result prints a final JSON object on stdout; shape is equivalent to:

{
  'ok': True,
  'result': {'key': 'value'},
  'messages': [{'level': 'info', 'message': '...'}],
}

Parse stdout as JSON for scripting; stderr still carries errors in human form unless commands only use Output. Use flush_json only where a command explicitly ends with buffered rows and no result envelope.

Standard workspace layout

workspace/
  autopilot/
    pyproject.toml
    plugins/
    projects/
      <name>/
        cli.py                # defines CLI subclass; entry MyCLI()()
        trainer.py            # builds Trainer with project Module
        ai/
        experiments/
          <slug>/
            manifest.json
            events.jsonl
            commands.json
        records/
          promotions/
          notes/
        datasets/

No workspace.toml, project.toml, or workflow TOML files -- project wiring lives in Python (cli.py, trainer.py).

Project CLI registration

Subclass AutoPilotCLI (or CLI) with project='<name>' on the class statement. CLI.__init_subclass__ stores project -> CLI class in CLI._project_registry. When autopilot -p <name> runs, CLI.run() may execute projects/<name>/cli.py via runpy, then instantiates the registered class if present.

Workspace commands

src/autopilot/cli/commands/workspace.py:

• autopilot workspace init -- creates the autopilot/ tree (projects, experiments, datasets, records, plugins, etc.); idempotent.
• autopilot workspace doctor -- validates expected directories under autopilot/.
• autopilot workspace tree -- ASCII tree of autopilot/ (bounded depth).

Project commands

src/autopilot/cli/commands/project.py:

• autopilot project list -- lists project directories under autopilot/projects/.
• autopilot project init <name> -- scaffolds a project directory with cli.py, module.py, and data.py from templates (use --bare to skip template files).
• autopilot project doctor <name> -- health checks for a project (e.g. cli.py, data dirs).

Project resolution

Order: --project / -p > current working directory under autopilot/projects/<name>/. Optional registered CLI subclass for that project name handles dispatch after cli.py import side effects.

CLIContext

src/autopilot/cli/context.py -- paths via paths.*. generator, judge, module come from the active CLI instance when CLI._run_direct() builds context.

Centralized paths

src/autopilot/core/paths.py -- single definitions for autopilot_dir, projects_dir, root(workspace, project), experiments, datasets, records, project_cli, etc.

Key files

• src/autopilot/cli/commands/workspace.py
• src/autopilot/cli/commands/project.py
• src/autopilot/core/paths.py
• src/autopilot/core/config.py
• src/autopilot/cli/context.py
• src/autopilot/cli/command.py -- CLI, project registry
• src/autopilot/cli/main.py -- AutoPilotCLI, main()
• src/autopilot/cli/resolvers.py -- make_subparser, add_global_flags
• src/autopilot/cli/output.py -- Output with result(), info(), table()
• src/autopilot/cli/expose.py -- ExposeRecord, ExposeCollector

Gotchas

• Overlays live under autopilot/projects/<name>/, not in src/autopilot/.
• project init creates cli.py, module.py, data.py from templates; it does not create trainer.py. Use --bare to skip template files.
• Paths resolve with Path.resolve(); --workspace defaults to ..
• Runtime and infrastructure settings belong in Python (constructors, Trainer, Module) and explicit CLI flags. Do not assume TOML workspace or workflow layers.