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

# CLI reference

> Every px0 command, grouped by the entity it acts on, with its flags.

px0's commands read as **entity, then verb**: `px0 workflows new`, `px0 brain search`, `px0 guidelines edit`. Once you know the entities, you can usually guess the command.

The only flat commands are the ones that act on the install rather than on anything in your store: `init`, `update`, `version`, `doctor`, `status`, and `completion`.

Add `--help` to any command for its own flags. `px0 config get --help` and `px0 config set --help` additionally list every settable key.

## Global flags

| Flag           | Effect                                                      |
| :------------- | :---------------------------------------------------------- |
| `--json`       | Machine-readable output where supported. Implies no colour. |
| `--no-color`   | Plain output, no colour or animation. Same as `NO_COLOR=1`. |
| `--help`, `-h` | Show help at whatever level it is given.                    |

Both work at the root (`px0 --json runs list`), and the subcommands that support `--json` accept it in place too.

## Exit codes

| Code | Meaning                                                                 |
| :--- | :---------------------------------------------------------------------- |
| `0`  | Success                                                                 |
| `1`  | User error - bad input, missing file, unknown id, failed validation     |
| `2`  | Connector error - an external app call failed or is not authorized      |
| `3`  | Model error - the coding-agent harness failed, timed out, or is missing |
| `4`  | Integrity error - the store's version history or index is inconsistent  |

## Confirmations

Every command that removes or revokes something asks first, and every one of them takes `--yes` to skip the question. With stdin not a terminal and no `--yes`, the command stops rather than assuming: `workflows rm`, `brain rm`, `guidelines rm`, `tools disconnect`, and `tools call` on a write tool.

## init

```bash theme={null}
px0 init [dir] [--harness claude|gemini|opencode|pi] [--composio-key KEY]
```

Scaffolds a store, asks for a Composio API key, and prints suggested next commands. Safe to run in a script: when stdin is not a terminal it skips the prompt and tells you to set the key later. Running against an existing store fills in anything missing and leaves the rest alone. See [Installation](/get-started/installation).

## workflows

| Command                                      | What it does                                                            |
| :------------------------------------------- | :---------------------------------------------------------------------- |
| `px0 workflows new`                          | Open an interview to describe and build a workflow                      |
| `px0 workflows run [id]`                     | Run one now; omit the id to pick from a list                            |
| `px0 workflows edit [id]`                    | Revise the stored request and rebuild                                   |
| `px0 workflows list`                         | Every workflow, plus any file that fails to parse                       |
| `px0 workflows show <id>`                    | Where its file is, what version it is on, and the file itself           |
| `px0 workflows validate [id]`                | Check frontmatter, tools, guidelines, and cron without running anything |
| `px0 workflows rm <id>`                      | Remove, keeping its history                                             |
| `px0 workflows rename <id> <new-id>`         | Rename the file and rewrite its `id`                                    |
| `px0 workflows copy <id> <new-id>`           | Fork a workflow to a new id                                             |
| `px0 workflows disable <id>` / `enable <id>` | Stop it firing, or let it fire again                                    |

**`new`** - `--yes` skips every prompt, `--id <id>` names it directly, `--no-clarify` skips the clarifying questions, `--no-discover` restricts it to curated tools, `--from-file <path>` reads the description from a file. See [Build a workflow](/workflows/build).

**`run`** - `--dry-run` stubs write tools, `--input KEY=VALUE` (repeatable) passes named values, `--stdin` reads piped text, `--output stdout|file` overrides the destination, `--timeout <duration>` overrides the workflow's own timeout, `--no-retry` attempts once regardless of the retry policy, `--quiet` suppresses decoration, `--json` prints the run record. See [Run a workflow](/workflows/run).

**`edit`** - takes `--yes`, `--no-clarify`, and `--no-discover`.

**`validate`** - `--json` prints one object per workflow with its errors. Exits `1` if anything is invalid, so it works in a pre-commit hook or CI.

See [Workflow files](/workflows/anatomy) for the full frontmatter reference.

## tools

| Command                       | What it does                                                         |
| :---------------------------- | :------------------------------------------------------------------- |
| `px0 tools list [service]`    | Every tool a workflow can call, read vs write, optionally by service |
| `px0 tools search [query]`    | Search Composio's catalogue of toolkits and tools                    |
| `px0 tools call <tool>`       | Call one tool with one set of arguments and print the result         |
| `px0 tools connect <app>`     | Authorize an app deliberately                                        |
| `px0 tools disconnect <app>`  | Revoke an app's authorization                                        |
| `px0 tools refresh [tool...]` | Re-read cached tool definitions from Composio                        |

`list --status` also asks Composio what is authorized, at one API call per toolkit. `px0 --json tools list` includes each tool's parameter schema.

**`search`** - `--toolkit <slug>` restricts to one toolkit, `--toolkits` lists toolkits instead of tools, `--limit N` caps the results.

**`call`** - `--arg KEY=VALUE` (repeatable) passes arguments, `--yes` skips the confirmation a write tool asks for.

**`connect`** - `--reconnect` drops the existing authorization first. **`disconnect`** - `--yes` skips the confirmation. **`refresh`** - `--forget` drops the cache instead of re-reading it.

See [Tools](/tools/catalogue) and [Connections](/tools/connections).

## brain

| Command                    | What it does                                      |
| :------------------------- | :------------------------------------------------ |
| `px0 brain add <source>`   | Ingest a URL, a YouTube link, or a local file     |
| `px0 brain refresh [path]` | Re-fetch an already-ingested source               |
| `px0 brain list`           | Every file in the brain                           |
| `px0 brain show <path>`    | One file: source, kind, and text                  |
| `px0 brain rm <path>`      | Remove a file and drop it from the index          |
| `px0 brain export <dir>`   | Copy the library elsewhere, keeping its structure |
| `px0 brain search <query>` | Retrieve matching passages                        |
| `px0 brain ask <question>` | Answer a question from the library                |
| `px0 brain reindex`        | Rebuild the retrieval index                       |

**`add`** - `--to <folder>` overrides the destination folder, `--from-file <path>` ingests every source listed in a file, one per line.

**`refresh`** - `--all` re-fetches everything with a recorded source, `--stale` re-fetches what has gone stale (plus every stub), `--days N` sets what counts as stale (default 30).

**`export`** - `--include-private` includes the private folder, held back by default.

**`search`** / **`ask`** - `--k N` sets how many passages to retrieve, `--kind {blog,paper,doc,video,stub}` narrows to one kind. `ask` also takes `--sources` to print citations.

See [The brain](/brain/library).

## guidelines

| Command                         | What it does                                             |
| :------------------------------ | :------------------------------------------------------- |
| `px0 guidelines list`           | Every guideline, numbered, with its first rule beside it |
| `px0 guidelines edit <name>`    | Open a guideline in your editor                          |
| `px0 guidelines show <name>`    | Print one guideline verbatim                             |
| `px0 guidelines rm <name>`      | Remove a guideline, keeping its history                  |
| `px0 guidelines log <claim-id>` | One claim's edit history                                 |

A claim id is `<file>#<slug>`, for example `commit-style.md#summary-line`. There is no `px0 guidelines new` - a guideline is only ever created by `px0 workflows new` drafting one from a workflow. See [Guidelines](/guidelines/overview).

## runs

| Command                    | What it does                                                   |
| :------------------------- | :------------------------------------------------------------- |
| `px0 runs`                 | Interactive browser over past runs                             |
| `px0 runs list`            | The same rows as plain text                                    |
| `px0 runs show <run-id>`   | The full JSON record                                           |
| `px0 runs output <run-id>` | What it produced, as recorded                                  |
| `px0 runs logs <run-id>`   | The raw log; `--follow` to tail                                |
| `px0 runs rerun <run-id>`  | Run that workflow again; a dry run reruns as a dry run         |
| `px0 runs why <run-id>`    | How the run reached its result                                 |
| `px0 runs cancel <run-id>` | Stop a run in flight; `--force` sends `SIGKILL`                |
| `px0 runs prune`           | Delete logs and records past retention; `--dry-run` to preview |
| `px0 runs open <run-id>`   | What it produced, reading the file as it is now                |

`list` takes `--workflow <id>`, `--failed`, `--since <age>` (`12h`, `7d`, `2w`), `--running`, and `--json`. `px0 runs` with no terminal falls back to the plain listing, and only the current store's runs are listed. See [Browse runs](/runs/browse).

## daemon

| Command                                 | What it does                           |
| :-------------------------------------- | :------------------------------------- |
| `px0 daemon install`                    | Install the scheduler for your OS      |
| `px0 daemon status`                     | Alive or not, last fires, next fires   |
| `px0 daemon start` / `stop` / `restart` | Control it                             |
| `px0 daemon serve`                      | Run it in the foreground               |
| `px0 daemon logs`                       | The daemon log; `--follow` to tail     |
| `px0 daemon uninstall`                  | Remove whatever `install` put in place |

`install` takes `--fallback-cron` to force cron over the native mechanism. See [Schedules and the daemon](/workflows/schedule).

## changes

| Command                          | What it does                           |
| :------------------------------- | :------------------------------------- |
| `px0 changes list`               | Every recorded change, newest first    |
| `px0 changes show <change-id>`   | One change's files, each with its diff |
| `px0 changes revert <change-id>` | Undo one change across all its files   |

`list` takes `--since <age>` (`12h`, `7d`, `2w`), `--actor <name>` (`builder`, `update`, `user:manual`), and `--json`. See [History](/guidelines/history).

## store

| Command                  | What it does                                           |
| :----------------------- | :----------------------------------------------------- |
| `px0 store list`         | Workflows, guidelines, and the brain in one pass       |
| `px0 store export <dir>` | Portable copy of content and history, secrets stripped |
| `px0 store import <dir>` | Load an exported store into this one                   |
| `px0 store path`         | Where the store is                                     |
| `px0 store verify`       | Check the store's own internal consistency             |

`export` strips secrets: the Composio key is blanked in the exported `config.toml`, and its version history is dropped from the export so the key is not recoverable from the history blobs either. `import` takes `--merge` to add what is missing and keep everything already here, or `--force` to let the import win on a collision - without either, importing into an existing store stops rather than silently overwriting. See [The store](/reference/store).

## config

| Command                        | What it does                                               |
| :----------------------------- | :--------------------------------------------------------- |
| `px0 config list`              | Every key with its value, default, and description         |
| `px0 config get <key>`         | One key's current value                                    |
| `px0 config set <key> <value>` | Validate and save one key                                  |
| `px0 config unset <key>`       | Drop a key's override, falling back to its default         |
| `px0 config edit`              | Open `config.toml` in your editor                          |
| `px0 config path`              | Where `config.toml` is                                     |
| `px0 config model`             | Pick a harness and model interactively, verifying it works |
| `px0 config composio [key]`    | Set the Composio API key; prompts and masks if omitted     |

See [Configuration](/reference/configuration).

## status

```bash theme={null}
px0 status [--hours N] [--json]
```

Whether anything needs attention, in one screen: the daemon, workflow counts, upcoming fires, recent runs and failures, and the same problems `doctor` and `runs list --failed` would surface separately - assembled from local state, with no network or model call. `--hours N` sets how far back a failure still counts as news (default 24). See [Status](/reference/status).

## doctor

```bash theme={null}
px0 doctor [--quick] [--json]
```

Runs every health check and prints a concrete fix for each failure. Exits `0` when all pass, `4` when any fail. `--quick` skips the slower checks that need a live subprocess or a filesystem walk.

The checks are `credentials`, `versions`, `locks`, `schema`, `connections`, `workflows`, `unreferenced_guidelines`, `update`, `daemon`, `harness`, `index`, and `private_folder`. See [Troubleshooting](/reference/troubleshooting).

## mcp

```bash theme={null}
px0 mcp serve [--allow-runs]
```

Exposes the brain and the workflow list over the Model Context Protocol, so a coding agent can discover and use them without being told how the CLI works. `--allow-runs` is required before a client can actually run a workflow. See [MCP](/reference/mcp).

## completion

```bash theme={null}
px0 completion {bash,zsh,fish}
```

Prints a shell completion script, generated from the command tree itself - workflow ids, config keys, and run ids complete too, read live from the store.

## update and version

```bash theme={null}
px0 version
px0 update [--check] [--channel stable|beta]
px0 update rollback
```

See [Updating px0](/reference/updating).

## Environment variables

| Variable                              | Effect                                                                                                                                     |
| :------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------- |
| `PX0_HOME`                            | Store location. Defaults to `~/.px0`.                                                                                                      |
| `COMPOSIO_API_KEY`                    | Composio key. Overrides `connectors.composio_api_key`.                                                                                     |
| `REQUESTS_CA_BUNDLE`, `SSL_CERT_FILE` | Set by px0 from `connectors.ca_bundle` so every outbound HTTPS call trusts an intercepting proxy. An explicit `SSL_CERT_FILE` always wins. |
| `NO_COLOR`                            | Plain output                                                                                                                               |
| `FORCE_COLOR`                         | Keep colour through a pipe                                                                                                                 |
| `TERM`                                | Controls coloured output                                                                                                                   |
| `PAGER`                               | Used by the run browser's log view, and for other long output                                                                              |