CLI reference

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`	Tool 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 delete, brain rm, guidelines rm, tools disconnect, and tools call on a write tool.

init

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.

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 delete <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
`px0 workflows recipes`	Sentences to start an interview from, when the page is blank
`px0 workflows health [id]`	What a workflow’s own runs say about it
`px0 workflows improve [id]`	Revise a workflow from what its runs actually did
`px0 workflows replay <id>`	Run its instructions against inputs a past run already had

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. 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. 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. health - --since <age> narrows the window, --fix applies the repairs px0 can make itself (one confirmation each), --yes skips those confirmations, --json prints the whole report. No model call and no network. improve - --since <age> narrows what it learns from, --dry-run shows the proposal and applies none of it, --show-evidence prints exactly what the model would be given and makes no model call, --yes skips every prompt, plus --no-clarify and --no-discover for the rebuild. replay - --run <id> picks the captured run (default the most recent), --against <file> compares alternative instructions, --fixtures lists what has been captured, --forget deletes them. See Improving a workflow. See Workflow files for the full frontmatter reference.

ask

px0 ask ["<question>"] [--route ROUTE] [--explain] [--k N] [--yes] [--json]
px0 ask [--continue] [--no-remember]

Routes one question to memory, your brain, a workflow, a single read-only tool, or a plain answer, and prints which it chose. With no question and a terminal, it opens a conversation instead. --route pins the destination (memory, brain, workflow, tool, answer). --explain prints the decision and stops. --continue carries on the last conversation; --no-remember skips the offer to keep what it taught px0. A workflow that can write is confirmed by name before ask will run it, unless --yes. Flat rather than under an entity, for the same reason status is: it acts across every group, and there is no single noun to put in front of it. px0 brain ask still exists and still means the narrow, brain-only thing. See Ask.

approvals

Command	What it does
`px0 approvals` / `px0 approvals list`	Drafted write calls waiting for a decision, oldest first
`px0 approvals show <id>`	Exactly what one call would send, and the output that prompted it
`px0 approvals edit <id>`	Change the arguments before sending
`px0 approvals approve <id>`	Send it, with the arguments you read
`px0 approvals reject <id>`	Throw the draft away
`px0 approvals purge`	Delete resolved approvals past retention

list - --all includes resolved ones, --workflow <id> narrows to one workflow. edit - --set KEY=VALUE (repeatable) changes one argument; omit it to open the arguments in $EDITOR as JSON. --note <why> records why. approve - --yes skips the confirmation. reject - --reason <why>, which px0 workflows improve later reads. purge - --days N overrides the retention window. See Approvals.

inbox

Command	What it does
`px0 inbox [list]`	What your scheduled workflows delivered, newest first
`px0 inbox read [id]`	Read one and mark it read; with no id, the oldest unread
`px0 inbox archive <id>`	Keep it but stop listing it
`px0 inbox clear`	Delete what you have read

list - --all includes what you have read, --workflow <id> narrows to one workflow. clear - --all deletes unread entries too. See Inbox.

memory

Command	What it does
`px0 memory [list]`	Everything px0 remembers about you; a pinned memory is marked `*`
`px0 memory add "<text>"`	Tell px0 something to remember
`px0 memory show <name>`	One memory in full
`px0 memory search "<query>"`	What px0 remembers about something
`px0 memory suggest`	What it thinks it should remember, from your corrections
`px0 memory forget <name>`	Remove one. Its history stays

add - --kind {fact,preference,person,project,place}, --subject <what>, --pin to always include it. suggest - --yes keeps all of them without asking. See Memory.

tools

Command	What it does
`px0 tools list [app]`	Every tool a workflow can call, read vs write, optionally by app
`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. A tool declared in tools/*.toml may name the environment variables it needs with env = ["DEPLOY_TOKEN"]. Declaring any narrows what the command can see to PATH, HOME, and the ones named, so a token meant for one tool is not handed to every other tool a workflow can reach. A declared variable that is not set is refused before the command runs. See Tools and 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.

guidelines

Command	What it does
`px0 guidelines list`	Every guideline, numbered, with its first claim 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.

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
`px0 runs mark <run-id>`	Say whether a run’s output was any good
`px0 runs events <run-id>`	The run’s structured event stream, one line per thing that happened
`px0 runs stats`	Runs rolled up by workflow

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. mark - --good [NOTE], --bad [NOTE], or --clear, with --note as an alternative way to attach the sentence. The note is what makes a mark worth having: “bad” says a run was wrong, “it missed the two PRs I reviewed” says how. stats - --since <age> narrows the window, --json prints the full rollup. See Browse runs.

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.

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.

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
`px0 store sync <dir>`	Bring this store and a shared folder into line

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. sync - --dry-run says what would move, --pull takes changes without sending any, --push sends without taking. Content merges file by file; the version history stays put, because it is a SQLite database and pointing a folder-syncing tool at it is how it gets corrupted. A file changed in both places is kept beside yours rather than overwritten. See The 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.

status

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.

doctor

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.

mcp

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.

completion

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

px0 version
px0 update [--check] [--channel stable|beta]
px0 update rollback

See Updating px0.

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

Get started

Ask

Workflows

Tools and connections

Approvals

Brain

Guidelines

Memory

Runs

Reference

Global flags

Exit codes

Confirmations

init

workflows

ask

approvals

inbox

memory

tools

brain

guidelines

runs

daemon

changes

store

config

status

doctor

mcp

completion

update and version

Environment variables

​Global flags

​Exit codes

​Confirmations

​init

​workflows

​ask

​approvals

​inbox

​memory

​tools

​brain

​guidelines

​runs

​daemon

​changes

​store

​config

​status

​doctor

​mcp

​completion

​update and version

​Environment variables

Global flags

Exit codes

Confirmations

init

workflows

ask

approvals

inbox

memory

tools

brain

guidelines

runs

daemon

changes

store

config

status

doctor

mcp

completion

update and version

Environment variables