google__adk-docs/docs/runtime/command-line.md

# Use the Command Line

<div class="language-support-tag">
  <span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v0.1.0</span><span class="lst-typescript">TypeScript v0.2.0</span><span class="lst-go">Go v0.1.0</span><span class="lst-java">Java v0.1.0</span>
</div>

ADK provides an interactive terminal interface for testing your agents. This is
useful for quick testing, scripted interactions, and CI/CD pipelines.

![ADK Run](../assets/adk-run.png)

## Run an agent

Use the following command to run your agent in the ADK command line interface:

=== "Python"

    ```shell
    adk run my_agent
    ```

=== "TypeScript"

    ```shell
    npx @google/adk-devtools run agent.ts
    ```

=== "Go"

    In Go, the command-line interface is not a standalone `adk` tool. Instead,
    you embed the launcher directly in your agent's `main.go`. The
    `full.NewLauncher()` helper bundles the console, web server, and other
    modes into a single binary, with **console as the default** when no
    subcommand keyword is given:

    ```go title="main.go"
    import (
        "google.golang.org/adk/v2/cmd/launcher"
        "google.golang.org/adk/v2/cmd/launcher/full"
    )

    func main() {
        // ... build your agent and config ...
        l := full.NewLauncher()
        if err := l.Execute(ctx, config, os.Args[1:]); err != nil {
            log.Fatalf("Run failed: %v\n\n%s", err, l.CommandLineSyntax())
        }
    }
    ```

    Run the agent in console mode with either of the following commands:

    ```shell
    go run agent.go           # console is the default sublauncher
    go run agent.go console   # or explicitly name the console subcommand
    ```

=== "Java"

    Create an `AgentCliRunner` class (see [Java Quickstart](../get-started/java.md)) and run:

    ```shell
    mvn compile exec:java -Dexec.mainClass="com.example.agent.AgentCliRunner"
    ```

This starts an interactive session where you can type queries and see agent
responses directly in your terminal.

=== "Python"

    ```shell
    Running agent my_agent, type exit to exit.
    [user]: What's the weather in New York?
    [my_agent]: The weather in New York is sunny with a temperature of 25°C.
    [user]: exit
    ```

=== "TypeScript"

    ```shell
    Running agent my_agent, type exit to exit.
    [user]: What's the weather in New York?
    [my_agent]: The weather in New York is sunny with a temperature of 25°C.
    [user]: exit
    ```

=== "Go"

    ```shell
    User -> What's the weather in New York?

    Agent -> The weather in New York is sunny with a temperature of 25°C.

    User ->
    ```

    To exit, press **Ctrl+C** or send EOF (**Ctrl+D**).

=== "Java"

    ```shell
    Running agent my_agent, type exit to exit.
    [user]: What's the weather in New York?
    [my_agent]: The weather in New York is sunny with a temperature of 25°C.
    [user]: exit
    ```

## Session options

!!! note "Python only"

    The `--save_session`, `--resume`, `--replay`, and `--session_id` options
    are available in the Python ADK CLI only. The Go console launcher does not
    support session save/resume/replay via command-line flags. In Go, session
    persistence is configured in code by providing a persistent
    `session.Service` implementation (such as `session/database`) to
    `launcher.Config`.

The `adk run` command includes options for saving, resuming, and replaying
sessions.

### Save sessions

To save the session when you exit:

```shell
adk run --save_session path/to/my_agent
```

You'll be prompted to enter a session ID, and the session will be saved to
`path/to/my_agent/<session_id>.session.json`.

You can also specify the session ID upfront:

```shell
adk run --save_session --session_id my_session path/to/my_agent
```

### Resume sessions

To continue a previously saved session:

```shell
adk run --resume path/to/my_agent/my_session.session.json path/to/my_agent
```

This loads the previous session state and event history, displays it, and allows
you to continue the conversation.

### Replay sessions

To replay a session file without interactive input:

```shell
adk run --replay path/to/input.json path/to/my_agent
```

The input file should contain initial state and queries:

```json
{
  "state": {"key": "value"},
  "queries": ["What is 2 + 2?", "What is the capital of France?"]
}
```

## Storage options

!!! note "Python only"

    The `--session_service_uri` and `--artifact_service_uri` command-line
    flags are available in the Python ADK CLI only. In Go, session and artifact
    services are configured in code when constructing `launcher.Config` — for
    example, using `session/database` for a persistent database-backed session
    store, or `artifact/gcsartifact` for Cloud Storage-backed artifacts.

| Option | Description | Default |
|--------|-------------|---------|
| `--session_service_uri` | Custom session storage URI | SQLite under `.adk/session.db` |
| `--artifact_service_uri` | Custom artifact storage URI | Local `.adk/artifacts` |
| `--memory_service_uri` | Custom memory service URI | In-memory |

### Example with storage options

```shell
adk run --session_service_uri "sqlite:///my_sessions.db" path/to/my_agent
```

## All options

=== "Python"

    | Option | Description |
    |--------|-------------|
    | `--save_session` | Save the session to a JSON file on exit |
    | `--session_id` | Session ID to use when saving |
    | `--resume` | Path to a saved session file to resume |
    | `--replay` | Path to an input file for non-interactive replay |
    | `--session_service_uri` | Custom session storage URI |
    | `--artifact_service_uri` | Custom artifact storage URI |
    | `--memory_service_uri` | Custom memory service URI |

=== "Go"

    !!! note "Go flags differ from Python"

        The Go console launcher does not support `--save_session`, `--resume`,
        `--replay`, `--session_id`, `--session_service_uri`, or
        `--artifact_service_uri`. These are Python CLI features. Session and
        artifact services are configured in Go code via `launcher.Config`.

    Flags are passed after the `console` keyword (or directly if `console` is
    the default):

    | Flag | Description | Default |
    |------|-------------|---------|
    | `-streaming_mode` | Streaming mode for agent responses (`none`\|`sse`) | Auto-detected (TTY → `sse`, pipe → `none`) |
    | `-shutdown-timeout` | Graceful shutdown wait time | `2s` |
    | `-otel_to_cloud` | Export OpenTelemetry data to GCP | `false` |

    For example, to force non-streaming output:

    ```shell
    go run agent.go console -streaming_mode none
    ```

    Or to force SSE streaming (token-by-token output):

    ```shell
    go run agent.go -streaming_mode sse
    ```