CLI Reference

This page is generated from the same argparse tree used by the praxist executable. The command implementation is the sole definition; rebuild the documentation after changing CLI arguments.

usage: praxist [-h] [--version] <command> ...

Global arguments¶

Argument	Required	Description
`-h`, `--help`	no	show this help message and exit
`--version`	no	show program's version number and exit

Commands¶

Command	Purpose
`praxist configure-llm`	Persist a built-in Praxist LLM provider profile.
`praxist docs`	Open or print the hosted Praxist documentation.
`praxist doctor`	Check Praxist host readiness.
`praxist examples`	List or install complete writable example projects.
`praxist install-skills`	Install bundled Praxist skills for Codex or Claude Code.
`praxist uninstall-skills`	Remove Praxist-managed agent skill registrations.
`praxist product-usage`	Review or change pseudonymous product-usage consent.
`praxist monitor`	Watch Praxist run state in a live read-only terminal dashboard.
`praxist resolve`	Resolve a task project's plugin manifest (no LLM calls).
`praxist resume`	Resume an interrupted Praxist run.
`praxist setup`	Configure this host for Praxist operation.
`praxist start`	Launch a new Praxist research run (registry-backed).
`praxist status`	List known Praxist experiment runs.
`praxist stop`	Stop a Praxist run by run_id, or stop everything with --all.
`praxist takeover`	Open Codex or Claude Code and hand off a project to Praxist takeover.
`praxist uninstall`	Remove the user-level Praxist installation.
`praxist user-agreement`	Review the Praxist License and User Agreement or inspect acceptance status.

`praxist configure-llm`¶

Persist a built-in Praxist LLM provider profile.

usage: praxist configure-llm [-h] --provider PROVIDER [--model MODEL]
                             [--agent-system {claude_sdk,codex_sdk}]
                             [--api-key-stdin | --api-key-env API_KEY_ENV | --no-api-key | --remove-api-key]
                             [--config-file CONFIG_FILE] [--project-env-file PROJECT_ENV_FILE]
                             [--print-source-command] [--json] [--dry-run]

Argument	Required	Description
`-h`, `--help`	no	show this help message and exit
`--provider`	yes	Built-in provider name or compatible provider plugin reference.
`--model`	no	Provider model name to persist.
`--agent-system`	no	Agent runtime selection to persist. Choices: `claude_sdk`, `codex_sdk`.
`--api-key-stdin`	no	Read the provider API key from stdin; a local TTY shows one * per character.
`--api-key-env`	no	Read the provider API key from this environment variable.
`--no-api-key`	no	Update non-secret provider settings without writing an API key.
`--remove-api-key`	no	Remove this provider's stored API key from the selected config file(s).
`--config-file`	no	Config file to update (default: $PRAXIST_CONFIG_FILE or the user config).
`--project-env-file`	no	Also write Praxist LLM config to this explicit task-local .env file.
`--print-source-command`	no	Print the shell command that loads the selected config file.
`--json`	no	Emit the result as JSON.
`--dry-run`	no	Validate and report changes without writing files.

`praxist docs`¶

Open or print the hosted Praxist documentation.

usage: praxist docs [-h] [--no-open]

Argument	Required	Description
`-h`, `--help`	no	show this help message and exit
`--no-open`	no	Print the documentation URL without opening a browser.

`praxist doctor`¶

Check Praxist host readiness.

usage: praxist doctor [-h] [--json] [--task-path TASK_PATH] [--config-file CONFIG_FILE]
                      [--agent-system {claude_sdk,codex_sdk}] [--model-provider MODEL_PROVIDER]
                      [--model MODEL] [--codex-native] [--target {auto,codex,claude}] [--advisory]

Argument	Required	Description
`-h`, `--help`	no	show this help message and exit
`--json`	no	Emit the readiness report as JSON.
`--task-path`	no	Also validate this task project and its runtime environment.
`--config-file`	no	Config file to inspect (default: $PRAXIST_CONFIG_FILE or the user config).
`--agent-system`	no	Check one research runtime (default: configured runtime or claude_sdk). Choices: `claude_sdk`, `codex_sdk`.
`--model-provider`	no	Check one model_provider ref using the same precedence as praxist start.
`--model`	no	Check this selected model (Codex-native verifies it in the account catalog).
`--codex-native`	no	Check codex_sdk with native OpenAI and the saved ChatGPT login.
`--target`	no	Check bundled skills for this agent host (default: detect managed installs). Choices: `auto`, `codex`, `claude`. Default: `auto`.
`--advisory`	no	Always return exit 0 while retaining readiness failures in the report.

`praxist examples`¶

List or install complete writable example projects.

usage: praxist examples [-h] <action> ...

Argument	Required	Description
`-h`, `--help`	no	show this help message and exit

`praxist install-skills`¶

Install bundled Praxist skills for Codex or Claude Code.

usage: praxist install-skills [-h] [--target {codex,claude}] [--target-dir TARGET_DIR]
                              [--mode {copy,symlink}] [--replace] [--force-unmanaged]
                              [--migrate-legacy-symlinks] [--dry-run] [--json]

Argument	Required	Description
`-h`, `--help`	no	show this help message and exit
`--target`	no	Skill host. Default: codex. Choices: `codex`, `claude`. Default: `codex`.
`--target-dir`	no	Override the target skill directory.
`--mode`	no	Register skills by copying package content or linking a source checkout. Choices: `copy`, `symlink`. Default: `copy`.
`--replace`	no	Refresh existing Praxist-managed entries; unmanaged paths require --force-unmanaged.
`--force-unmanaged`	no	With --replace, back up and replace unmanaged entries whose names exactly match bundled Praxist skills. Unrelated skills are untouched.
`--migrate-legacy-symlinks`	no	With --replace, explicitly adopt old Praxist repo-style symlinks that predate the ownership manifest.
`--dry-run`	no	Report actions without changing the target directory.
`--json`	no	Emit the result as JSON.

`praxist uninstall-skills`¶

Remove Praxist-managed agent skill registrations.

usage: praxist uninstall-skills [-h] [--target {codex,claude}] [--target-dir TARGET_DIR] [--dry-run]
                                [--json]

Argument	Required	Description
`-h`, `--help`	no	show this help message and exit
`--target`	no	Skill host. Default: codex. Choices: `codex`, `claude`. Default: `codex`.
`--target-dir`	no	Override the target skill directory.
`--dry-run`	no	Report removals without changing the target directory.
`--json`	no	Emit the result as JSON.

`praxist product-usage`¶

Review or change pseudonymous V2 product-usage consent. Withdrawal stops future capture and deletes unsent local events; delivered events expire through scheduled retention.

usage: praxist product-usage [-h] <command> ...

Argument	Required	Description
`-h`, `--help`	no	show this help message and exit

Render a live read-only dashboard from praxist status, orchestrator snapshots, peer memory health, recent logs, and lightweight host load. The dashboard runs directly in the current terminal and never controls the Praxist research process.

usage: praxist --monitor [-h] [--run-id RUN_ID] [--run-dir RUN_DIR] [--task-path TASK_PATH]
                         [--latest] [--interval INTERVAL] [--once] [--follow] [--no-clear] [--plain]
                         [--log-lines LOG_LINES] [--peer-limit PEER_LIMIT]

Argument	Required	Description
`-h`, `--help`	no	show this help message and exit
`--run-id`	no	Monitor one run id.
`--run-dir`	no	Monitor one run dir.
`--task-path`	no	Prefer active rows for this task path.
`--latest`	no	Select the latest active run row when more than one exists.
`--interval`	no	Frame interval in seconds (default: 0.2 for the fullscreen TUI, 1 for plain text).
`--once`	no	Render one frame and exit.
`--follow`	no	Keep refreshing even when stdout is not an interactive terminal.
`--no-clear`	no	Append frames instead of clearing the terminal between refreshes.
`--plain`	no	Use the legacy plain-text monitor instead of the fullscreen TUI.
`--log-lines`	no	Recent log lines to show for the selected run (default: 18). Default: `18`.
`--peer-limit`	no	Maximum peer rows to render (default: 24). Default: `24`.

`praxist resolve`¶

Discover and resolve a task project's plugin manifest without making any LLM calls. Equivalent to:

python -m praxist.run run --task-path <path> --resolve-only --local

Exits non-zero on resolution failure (manifest schema error, missing plugin, etc.). On success, emits a JSON document on stdout summarizing the resolved run identity.

usage: praxist resolve [-h] [--config-file CONFIG_FILE] [--agent-system {claude_sdk,codex_sdk}]
                       [--workspace WORKSPACE] [--run-dir RUN_DIR] [--runtime RUNTIME]
                       [--codex-native] [--model-provider MODEL_PROVIDER]
                       [--budget-policy BUDGET_POLICY] [--credential-profile CREDENTIAL_PROFILE]
                       [--model MODEL] [--result-summary RESULT_SUMMARY]
                       [task_path]

Argument	Required	Description
`-h`, `--help`	no	show this help message and exit
`task_path`	no	Path to the task project directory (default: current directory). Default: `.`.
`--config-file`	no	Config file to load (default: $PRAXIST_CONFIG_FILE or the user config).
`--agent-system`	no	Agent system used to resolve runtime/provider defaults. Choices: `claude_sdk`, `codex_sdk`.
`--workspace`	no	Workspace directory (default: current working directory). Default: ``.
`--run-dir`	no	Override run artifact directory. Defaults to the task project's runtime_outputs.root / experiments directory; paths inside the Praxist source checkout are rejected. Default: ``.
`--runtime`	no	Override agent_runtime plugin ref. Default: ``.
`--codex-native`	no	Resolve with codex_sdk, native OpenAI, and saved ChatGPT login while ignoring API-key/custom-endpoint configuration.
`--model-provider`	no	Override model_provider plugin ref. Default: ``.
`--budget-policy`	no	Override budget_policy plugin ref. Default: ``.
`--credential-profile`	no	Override credential profile name (rarely needed for resolve-only). Default: ``.
`--model`	no	Override agent model. Not used by resolve-only itself, but propagated for parity. Default: ``.
`--result-summary`	no	Validate one evaluator-produced JSON summary against the task's maturity telemetry contract before resolving. Default: ``.

`praxist resume`¶

Continue an existing Praxist run directory from its last safe completed generation boundary. The target may be a registry run_id from praxist status or a direct experiments/run_* path.

usage: praxist resume [-h] [--task-path TASK_PATH] [--config-file CONFIG_FILE]
                      [--agent-system {claude_sdk,codex_sdk}] [--runtime RUNTIME_REF]
                      [--codex-native] [--model MODEL] [--model-provider MODEL_PROVIDER_REF]
                      [--strategy {auto,mixed,explore,exploit}] [--cohort COHORT]
                      [--generations GENERATIONS] [--server] [--daemonize]
                      [--resume-policy {completed_generation}] [--force]
                      [--startup-timeout STARTUP_TIMEOUT] [--json]
                      target

Argument	Required	Description
`-h`, `--help`	no	show this help message and exit
`target`	yes	Registry run_id or path to an existing Praxist run directory.
`--task-path`	no	Override task project path when resuming from a run directory.
`--config-file`	no	Config file to load (default: $PRAXIST_CONFIG_FILE or the user config).
`--agent-system`	no	Override agent system for the resumed launch. Choices: `claude_sdk`, `codex_sdk`.
`--runtime`	no	Override agent_runtime plugin ref.
`--codex-native`	no	Resume in Codex-native saved-login mode without provider API keys.
`--model`	no	Override model name.
`--model-provider`	no	Override model_provider plugin ref.
`--strategy`	no	Override frontier strategy. Choices: `auto`, `mixed`, `explore`, `exploit`.
`--cohort`	no	Cohort size override (exported as COHORT_SIZE).
`--generations`	no	Maximum generations override (exported as MAX_GENERATIONS).
`--server`	no	Disable --local mode (server mode).
`--daemonize`	no	Use the same double-fork daemon launch path as praxist start.
`--resume-policy`	no	Resume policy forwarded to praxist.run. Choices: `completed_generation`. Default: `completed_generation`.
`--force`	no	Allow resume only when an old registry entry's process ownership cannot be verified. It never overrides a verified live controller.
`--startup-timeout`	no	Seconds to wait for resume startup artifacts. Default: `30.0`.
`--json`	no	Emit one JSON document on stdout instead of the operator summary.

`praxist setup`¶

Pip-first Praxist host setup. Run this after installing the package and runtime extras. It writes only Praxist user-level configuration and Praxist-managed agent skill registrations; it does not install global agent CLIs or task-specific dependencies.

usage: praxist setup [-h] [--agent-system {claude_sdk,codex_sdk}] [--provider PROVIDER]
                     [--model MODEL] [--api-key-stdin | --api-key-env API_KEY_ENV | --no-api-key]
                     [--interactive]
                     [--profile {codex-native,deepseek-api,openrouter-api,anthropic-api}]
                     [--list-profiles] [--agent-managed] [--install-skills {codex,claude,none}]
                     [--config-file CONFIG_FILE] [--json] [--dry-run] [--skip-doctor]

Argument	Required	Description
`-h`, `--help`	no	show this help message and exit
`--agent-system`	no	Agent runtime selection to persist. Choices: `claude_sdk`, `codex_sdk`.
`--provider`	no	Built-in provider name to configure.
`--model`	no	Provider model name to persist.
`--api-key-stdin`	no	Read the provider API key from stdin; a local TTY shows one * per character.
`--api-key-env`	no	Read the provider API key from this environment variable.
`--no-api-key`	no	Configure a supported no-key authentication route.
`--interactive`	no	Review the License and User Agreement, choose optional privacy, and select a coherent runtime profile in a local TTY wizard.
`--profile`	no	Apply one complete profile; a missing API key is requested in the local terminal. Choices: `codex-native`, `deepseek-api`, `openrouter-api`, `anthropic-api`.
`--list-profiles`	no	List supported setup profiles as JSON and exit without changes.
`--agent-managed`, `--codex-managed`	no	Report the read-only agent-managed first-use decision state and next required action as JSON. --codex-managed remains a compatibility alias.
`--install-skills`	no	Install bundled skills for an agent host (interactive default: codex). Choices: `codex`, `claude`, `none`.
`--config-file`	no	Config file to update (default: $PRAXIST_CONFIG_FILE or the user config).
`--json`	no	Emit setup and readiness results as JSON.
`--dry-run`	no	Validate and report changes without writing files.
`--skip-doctor`	no	Skip the final readiness report.

`praxist start`¶

Async launcher: starts python -m praxist.run run in a new session, redirects stdout/stderr to a run-local log file, and writes a registry entry under $PRAXIST_STATE_DIR/runs/.

Pass --task-path / --model / --model-provider to override the resolved task and runtime configuration.

usage: praxist start [-h] [--task-path TASK_PATH] [--config-file CONFIG_FILE]
                     [--agent-system {claude_sdk,codex_sdk}] [--runtime RUNTIME_REF]
                     [--codex-native] [--run-dir RUN_DIR] [--resume] [--resume-from RESUME_FROM]
                     [--resume-policy {completed_generation}] [--model MODEL]
                     [--model-provider MODEL_PROVIDER_REF] [--strategy {auto,mixed,explore,exploit}]
                     [--cohort COHORT] [--generations GENERATIONS] [--server] [--daemonize]
                     [--startup-timeout STARTUP_TIMEOUT] [--json]

Argument	Required	Description
`-h`, `--help`	no	show this help message and exit
`--task-path`	no	Task project directory (default: $TASK_PATH or the current directory).
`--config-file`	no	Config file to load (default: $PRAXIST_CONFIG_FILE or the user config).
`--agent-system`	no	Agent system the launched run will use. Default: $PRAXIST_AGENT_SYSTEM if set, else 'claude_sdk'. Recognised values: claude_sdk (default), codex_sdk. Choices: `claude_sdk`, `codex_sdk`.
`--runtime`	no	Explicit `agent_runtime:*` plugin ref. Wins over the agent-system mapping when set.
`--codex-native`	no	Use codex_sdk with native OpenAI and saved ChatGPT login, ignoring API-key and custom-endpoint settings from process/config/task env.
`--run-dir`	no	Explicit run directory (default: <task>/experiments/run_<ts>_<task>).
`--resume`	no	Resume an existing run directory instead of requiring fresh artifacts.
`--resume-from`	no	Path to an existing run directory to resume. Equivalent to --run-dir <path> --resume.
`--resume-policy`	no	Resume policy forwarded to praxist.run. Choices: `completed_generation`. Default: `completed_generation`.
`--model`	no	Model name forwarded to the runtime; defaults depend on provider.
`--model-provider`	no	Provider plugin ref (e.g. model_provider:deepseek_alias). Default cascades from agent system: claude_sdk → deepseek_alias when DEEPSEEK_API_KEY is set, then openrouter when OPENROUTER_API_KEY is set, then anthropic_messages; codex_sdk follows the same credential-aware selection and falls back to openai_compatible.
`--strategy`	no	Frontier strategy (auto\|mixed\|explore\|exploit). Choices: `auto`, `mixed`, `explore`, `exploit`. Default: `auto`.
`--cohort`	no	Cohort size override (exported as COHORT_SIZE).
`--generations`	no	Maximum generations override (exported as MAX_GENERATIONS).
`--server`	no	Disable --local mode (server mode).
`--daemonize`	no	Double-fork the launcher before spawning so the workload survives when the launching shell's process tree is reaped. Required for sandboxed launcher contexts (agent tool shells, CI runners, Docker `--init`). The default `start_new_session=True` path is fine for a normal terminal.
`--startup-timeout`	no	Seconds to wait for startup artifacts before returning. A live run that exceeds the deadline remains in 'starting' state (default 30). Default: `30.0`.
`--json`	no	Emit one JSON document on stdout instead of the operator table.

`praxist status`¶

Merge the run registry written by praxist start with a cross-platform ps scan to list every Praxist run the operator should know about.

Rows are tagged with their source: registry (managed run, PID alive), ps-only (matching process without a registry entry — e.g. started through a direct Python invocation), or stale (registry entry whose PID is gone).

usage: praxist status [-h] [--json] [--run-id RUN_ID] [--task-path TASK_PATH] [--active] [--latest]

Argument	Required	Description
`-h`, `--help`	no	show this help message and exit
`--json`	no	Emit one JSON document on stdout instead of the plain-text table.
`--run-id`	no	Show only this registry run id.
`--task-path`	no	Show runs for this task directory.
`--active`	no	Show only live local runs.
`--latest`	no	Show only the newest matching run.

`praxist stop`¶

praxist stop <run_id> terminates one specific run via its registry entry. praxist stop --all terminates every Praxist-recognised process — by default the union of registry entries and ps-scan matches.

Registry-backed runs close new admission before discovery. Both modes send SIGTERM, wait --grace seconds, then SIGKILL any process still alive; registry-backed runs also perform a bounded stable-empty rescan for late children.

usage: praxist stop [-h] [--all] [--registry-only] [--ps-scan-only] [--grace GRACE_SECONDS] [--gc]
                    [--dry-run] [--json]
                    [run_id]

Argument	Required	Description
`-h`, `--help`	no	show this help message and exit
`run_id`	no	Run id (filename stem of $PRAXIST_STATE_DIR/runs/<run_id>.json).
`--all`	no	Stop every recognised Praxist run (registry + ps-scan by default).
`--registry-only`	no	With --all: only target registry-managed runs.
`--ps-scan-only`	no	With --all: only target unregistered runs found by the process scan.
`--grace`	no	Seconds to wait after SIGTERM before SIGKILL (default 5.0). Default: `5.0`.
`--gc`	no	Remove stale registry entries. A stale entry is one whose recorded PID is no longer alive, or whose live command line no longer matches the prefix recorded at `praxist start` time (PID recycling). No signals are sent.
`--dry-run`	no	Show what would be signalled without sending any signals. With --gc, list the would-be-removed entries without deleting any files.
`--json`	no	Emit a JSON outcome document instead of the operator summary.

`praxist takeover`¶

Open Codex or Claude Code and hand off a project to Praxist takeover.

usage: praxist takeover [-h] [--task-path TASK_PATH] [--codex-native | --configured-provider]
                        [--operator {codex,claude}] [--yes] [--dry-run] [--json]

Argument	Required	Description
`-h`, `--help`	no	show this help message and exit
`--task-path`	no	Research project to hand off (default: select locally or use the current directory).
`--codex-native`	no	Use the no-key Codex-native takeover skill.
`--configured-provider`	no	Use the configured-provider takeover skill.
`--operator`	no	Agent CLI that hosts the takeover workflow. Default: codex. Choices: `codex`, `claude`. Default: `codex`.
`--yes`	no	Launch without the final Enter confirmation.
`--dry-run`	no	Show the redacted handoff without starting the agent CLI.
`--json`	no	Emit the redacted handoff as JSON.

`praxist uninstall`¶

Remove Praxist-managed CLI files, runtime environment, agent skills, configuration, state, and cache. Research projects, task environments, run directories, agent CLIs, Python, and uv are never removed.

usage: praxist uninstall [-h] [--venv-dir VENV_DIR] [--bin-dir BIN_DIR] [--skills-dir SKILLS_DIR]
                         [--keep-user-data] [--dry-run] [--json]

Argument	Required	Description
`-h`, `--help`	no	show this help message and exit
`--venv-dir`	no	Override the Praxist-managed virtualenv path.
`--bin-dir`	no	Override the user bin directory containing Praxist entrypoints.
`--skills-dir`	no	Override skill removal with one explicit managed directory.
`--keep-user-data`	no	Keep Praxist configuration, registry state, product-usage state, and cache.
`--dry-run`	no	Validate ownership and report removals without changing files.
`--json`	no	Emit one machine-readable result document.

`praxist user-agreement`¶

Review the Praxist License and User Agreement or inspect acceptance status.

usage: praxist user-agreement [-h] <command> ...

Argument	Required	Description
`-h`, `--help`	no	show this help message and exit