CLI reference

astro otto

This command is only available on Astro.
Labs
This feature is in Labs.

Launch Otto, Astronomer’s data engineering agent, in your terminal. Otto helps you author, upgrade, debug, and manage Airflow Dags with deep context about your project and environment.

The astro otto command handles binary management, authentication, and local Airflow discovery automatically. All flags and arguments passed to astro otto are forwarded directly to Otto. For more information about Otto’s capabilities, see the Otto overview.

Usage

$astro otto [flags/args forwarded to Otto]
$astro otto update
$astro otto version

When run without a prompt, Otto opens an interactive terminal user interface. When a prompt is provided, Otto runs in one-shot mode and exits after responding.

Subcommands

SubcommandDescription
astro otto updateUpdate the Otto binary to the latest version
astro otto versionPrint the installed Otto version and check for updates

The first time you run astro otto, the CLI downloads the Otto binary to ~/.astro/bin/otto. On subsequent launches, the CLI checks for newer releases and applies them automatically before launching the agent. Set otto.auto_update to false to opt out and apply updates manually with astro otto update.

Otto versions independently of the Astro CLI. You don’t need to upgrade the Astro CLI to pick up new Otto features or fixes. Use astro otto update to pull the latest Otto release at any time.

Options

All options are forwarded to Otto.

OptionDescription
--mode <mode>Output mode: interactive (default), text, or json
--continue, -cResume the most recent session
--resume, -rOpen an interactive picker to choose a previous session
--session <path>Open a specific session file
--no-sessionRun without saving session history
--streamForce streaming on in text mode
--no-streamDisable streaming in text mode
--output-schemaRequire a structured final answer matching a JSON schema. Accepts a raw JSON string or @path/to/file.json. Headless modes only
--allowed-tools <names>Restrict active tools to a comma-separated allowlist
--permission-mode <mode>Set the starting permission mode: default, acceptEdits, confirmEdits, plan, or bypassPermissions. See Otto permissions
--skip-permissionsDisable the permission layer for the session. Coerces the mode to bypassPermissions; bypass-immune safety checks still fire
--extension <name>Enable a bundled extension. Repeatable. See Otto extensions
--no-extension <name>Disable a bundled extension. Repeatable
--model <id>Override the default model
--provider <name>Override the model provider
--list-models [search]List available models, optionally filtered
--version, -vPrint the Otto version and exit

Usage modes

astro otto supports three modes via --mode:

  • interactive (default): Full TUI with streaming output, tool call rendering, and session persistence. In a session, use / commands like /airflow (project context), /skills (browse and load skills), /model (switch the active model), /permissions, /extensions, /bootstrap, and /remember.
  • text: Plain-text response on stdout. Useful for piping to other tools or shell scripts. Streams to a TTY by default and suppresses streaming when piped or redirected. Override with --stream or --no-stream.
  • json: Newline-delimited JSON event stream covering messages, tool calls, tool results, and session lifecycle. Useful for programmatic integration.

Sessions

Otto persists every session to disk by default. Use --continue to resume the most recent, --resume to pick from an interactive list, or --session <path> to open a specific file. Session files are stored as JSONL at ~/.astro/otto/sessions/. Pass --no-session for ephemeral runs that don’t save history, which is useful in CI.

Headless mode flags

--output-schema (in text and json modes only) requires Otto to return a final answer matching a JSON schema. It accepts a raw JSON string or @path/to/file.json. --allowed-tools <names> restricts active tools to a comma-separated allowlist.

Model selection

Otto supports models from OpenAI, Anthropic, and Google through the Astronomer Gateway. The exact set available to your Organization is fetched at runtime.

In an interactive session, run /model to browse the current list and switch mid-session. To pin a model at launch or in headless modes, pass --model <id> and optionally --provider <name>. Run astro otto --list-models [search] to list what’s available from your shell.

Configuration

astro otto sets ASTRO_TOKEN, ASTRO_DOMAIN, ASTRO_ORGANIZATION, and the local AIRFLOW_* variables automatically. For the full list of environment variables, config files, and settings precedence, see Otto settings.

Examples

$# Launch the interactive TUI
$astro otto
$
$# Start the TUI with an initial prompt
$astro otto "summarize this Airflow project"
$
$# One-shot question in text mode
$astro otto --mode text "describe the Dags in this project"
$
$# One-shot without saving session history
$astro otto --mode text --no-session "what Airflow version am I running?"
$
$# Resume the most recent session
$astro otto --continue
$
$# List available models
$astro otto --list-models
$
$# Use a smaller model
$astro otto --model gpt-5.4-mini
$
$# Update Otto to the latest version
$astro otto update
$
$# Check the installed Otto version
$astro otto version