> Call the `diagnose` tool first. Full index: /llms.txt. Errors: /reference/problems.

# CLI commands

Add `--json` to any command to get one JSON value per result. Every value carries `schema_version` 2.

## Flags of every command

| Flag               | What it does                                           |
| ------------------ | ------------------------------------------------------ |
| `--json`           | print one JSON value per result (events as JSON lines) |
| `--no-interactive` | never ask a question or open a browser                 |
| `--verbose`        | write sanitized diagnostics to stderr                  |
| `--version`        | print the build, schema and protocol epoch             |

## `talotrace doctor`

Check this computer, your app's ports and the connection. Read-only.

| Flag        | What it does                                              |
| ----------- | --------------------------------------------------------- |
| `--offline` | skip the checks that need the network                     |
| `--ports`   | comma-separated local ports your app must be listening on |
| `--timeout` | give up on one request after this long                    |

## `talotrace login`

Sign in to TaloTrace. Tunnels only, unless you pass --tools.

| Flag           | What it does                                              |
| -------------- | --------------------------------------------------------- |
| `--no-browser` | print the sign-in URL here instead of opening a browser   |
| `--tools`      | also let this computer start runs and read their evidence |

## `talotrace logout`

Revoke and forget the sign-in on this computer.

| Flag           | What it does                                              |
| -------------- | --------------------------------------------------------- |
| `--all-scopes` | end every sign-in of this server, not just the active one |
| `--timeout`    | give up on one request after this long                    |

## `talotrace status`

Show the selected profile and the local sign-in. Needs no network.

## `talotrace version`

Show the build, schema and protocol epoch. Works offline.

## `talotrace connect`

Serve local ports to TaloTrace runs until you press Ctrl-C.

## `talotrace dev`

Start a live phone for your app (React Native, Flutter).

| Flag        | What it does                                                                                              |
| ----------- | --------------------------------------------------------------------------------------------------------- |
| `--apk`     | a dev-client APK to upload (skipped when this computer uploaded the same bytes)                           |
| `--app`     | TaloTrace app id (remembered per folder)                                                                  |
| `--build`   | an uploaded dev-client build id (remembered per folder)                                                   |
| `--cloud`   | serve Metro from a TaloTrace cloud workspace: this machine needs no Metro and no adb                      |
| `--flutter` | serve this directory as a Flutter app (found from pubspec.yaml without it)                                |
| `--hot`     | Flutter: hot reload each save through flutter attach on this machine                                      |
| `--port`    | the port Metro serves                                                                                     |
| `--project` | TaloTrace project id (remembered per folder)                                                              |
| `--scheme`  | Expo: the dev client's URL scheme (default exp+\<slug> from app.json); a bare React Native app needs none |

## `talotrace dev attach`

Join this folder's live phone from another terminal.

| Flag        | What it does                                            |
| ----------- | ------------------------------------------------------- |
| `--session` | the live phone to use (default: the one of this folder) |

## `talotrace dev rebuild`

Install a rebuilt APK on the live phone and keep its app data.

| Flag    | What it does                                                                           |
| ------- | -------------------------------------------------------------------------------------- |
| `--apk` | the rebuilt APK: a dev client after a native change, or a Flutter debug APK (required) |

## `talotrace dev status`

Show the live phone of this folder.

| Flag        | What it does                                            |
| ----------- | ------------------------------------------------------- |
| `--session` | the live phone to use (default: the one of this folder) |
| `--timeout` | give up on one request after this long                  |

## `talotrace dev stop`

Stop the live phone and show any cleanup still pending.

| Flag        | What it does                                            |
| ----------- | ------------------------------------------------------- |
| `--session` | the live phone to use (default: the one of this folder) |
| `--timeout` | give up on one request after this long                  |

## `talotrace dev sync`

Send this folder's source to its cloud workspace.

| Flag        | What it does                           |
| ----------- | -------------------------------------- |
| `--timeout` | give up on one request after this long |

## `talotrace device`

Drive the live phone: tap, type, swipe, key, open, screenshot, logs.

## `talotrace device key`

Press back or home.

| Flag        | What it does                                            |
| ----------- | ------------------------------------------------------- |
| `--session` | the live phone to use (default: the one of this folder) |
| `--timeout` | give up on one request after this long                  |

## `talotrace device logs`

Print the app's recent log lines.

| Flag        | What it does                                                       |
| ----------- | ------------------------------------------------------------------ |
| `--session` | the live phone to use (default: the one of this folder)            |
| `--since`   | only lines from the last this many seconds (all kept lines when 0) |
| `--timeout` | give up on one request after this long                             |

## `talotrace device open`

Open a link in the phone (an allowed app scheme).

| Flag        | What it does                                            |
| ----------- | ------------------------------------------------------- |
| `--session` | the live phone to use (default: the one of this folder) |
| `--timeout` | give up on one request after this long                  |

## `talotrace device screenshot`

Save a screenshot and print its path.

| Flag        | What it does                                                    |
| ----------- | --------------------------------------------------------------- |
| `--out`     | where to save the PNG (default: a dated name in this directory) |
| `--session` | the live phone to use (default: the one of this folder)         |
| `--timeout` | give up on one request after this long                          |

## `talotrace device swipe`

Swipe the screen.

| Flag          | What it does                                            |
| ------------- | ------------------------------------------------------- |
| `--direction` | up, down, left or right                                 |
| `--session`   | the live phone to use (default: the one of this folder) |
| `--timeout`   | give up on one request after this long                  |

## `talotrace device tap`

Tap a visible label or a point of the screen.

| Flag        | What it does                                            |
| ----------- | ------------------------------------------------------- |
| `--session` | the live phone to use (default: the one of this folder) |
| `--target`  | the visible text or accessibility label to tap          |
| `--timeout` | give up on one request after this long                  |
| `--x`       | horizontal position, a fraction from 0 to 1 (with --y)  |
| `--y`       | vertical position, a fraction from 0 to 1 (with --x)    |

## `talotrace device type`

Type text into a field.

| Flag           | What it does                                                |
| -------------- | ----------------------------------------------------------- |
| `--session`    | the live phone to use (default: the one of this folder)     |
| `--target`     | the field to type into (the focused one when none is named) |
| `--text`       | the text to type (a sensitive value belongs on stdin)       |
| `--text-stdin` | read the text from stdin                                    |
| `--timeout`    | give up on one request after this long                      |
| `--x`          | horizontal position, a fraction from 0 to 1 (with --y)      |
| `--y`          | vertical position, a fraction from 0 to 1 (with --x)        |

## `talotrace run`

Start a run and return once it is admitted.

| Flag            | What it does                                                                                               |
| --------------- | ---------------------------------------------------------------------------------------------------------- |
| `--build`       | run this uploaded build on a phone of its own instead of the live phone                                    |
| `--max-credits` | refuse the run if it could cost more than this many credits (a decimal)                                    |
| `--request-id`  | a UUID naming this run: sending the same one again never starts a second run (default: a new one, printed) |
| `--reset`       | what a live run resets on the phone first: none or app_data                                                |
| `--suite`       | run this test plan instead of naming scenarios                                                             |
| `--timeout`     | give up on one request after this long                                                                     |

## `talotrace mcp`

Run the stdio MCP server for your coding agent.

| Flag      | What it does                                                                        |
| --------- | ----------------------------------------------------------------------------------- |
| `--idle`  | close a tunnel after this long without a tool call naming its port or a run         |
| `--ports` | comma-separated extra local ports every tunnel serves (a local API on another port) |

> Every talotrace command and flag.

## Docs

- [Exit codes](https://docs.talotrace.ai/reference/cli/exit-codes.md): What the process exit code says.