> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# astro otto

<Info>
  This command is only available on Astro.
</Info>

<Info>
  **Labs**

  This feature is in [Labs](/docs/astro/feature-previews).
</Info>

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](/docs/astro/otto-overview).

## Usage

```bash wrap theme={null}
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

| Subcommand           | Description                                            |
| -------------------- | ------------------------------------------------------ |
| `astro otto update`  | Update the Otto binary to the latest version           |
| `astro otto version` | Print 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`.

<Note>
  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.
</Note>

## Options

All options are forwarded to Otto.

| Option                     | Description                                                                                                                                                 |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--mode <mode>`            | Output mode: `interactive` (default), `text`, or `json`                                                                                                     |
| `--persona <name>`         | Run the main agent as a named persona. Built-ins are `explorer` and `reviewer`. See [Personas](#personas)                                                   |
| `--continue`, `-c`         | Resume the most recent session                                                                                                                              |
| `--resume`, `-r`           | Open an interactive picker to choose a previous session                                                                                                     |
| `--session <path>`         | Open a specific session file                                                                                                                                |
| `--no-session`             | Run without saving session history                                                                                                                          |
| `--stream`                 | Force streaming on in text mode                                                                                                                             |
| `--no-stream`              | Disable streaming in text mode                                                                                                                              |
| `--output-schema`          | Require 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](/docs/astro/otto-permissions) |
| `--skip-permissions`       | Disable 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](/docs/astro/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`, `-v`          | Print 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.

### Personas

Use `--persona <name>` to run the main agent as a named persona. A persona sets the system prompt, tool allowlist, tier (which maps to a model), permission mode, and output schema when the persona declares one. Otto ships two built-in personas:

* **`explorer`**: Tuned for read-only exploration of a project.
* **`reviewer`**: Tuned for code review. The Otto review action runs `astro otto --persona reviewer` to review pull requests and merge requests. See [Review code with Otto](/docs/astro/otto-code-review).

Explicit `--model`, `--allowed-tools`, `--permission-mode`, and `--output-schema` flags override the persona's defaults. A persona-supplied output schema is dropped in interactive mode, which has no structured-output surface.

## 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](/docs/astro/otto-settings).

## Examples

```bash wrap theme={null}
# 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
```

## Related commands

* [`astro login`](/docs/cli/v1.42/astro-login)
* [`astro dev start`](/docs/cli/v1.42/astro-dev-start)
* [`astro deploy`](/docs/cli/v1.42/astro-deploy)