CLI reference

Every command supports --help. Global flags precede the subcommand.

Global flags

valved [--project-dir PATH] [--env-file PATH] [--target NAME] <command>

Flag	Meaning
`--project-dir PATH`	Project root (dir containing `valved.toml`). Defaults to cwd.
`--env-file PATH`	`.env` path. Defaults to `<project-dir>/.env`.
`--target NAME`	Active target; overrides `$VALVED_TARGET` and `default_target`.

Set VALVED_NO_DOTENV=1 to disable .env auto-loading.

Lifecycle

valved init [DIR] [--with-dbt] [--dbt-path P | --dbt-url U [--dbt-branch B]]
            [--with-dlt] [--external-postgres URL] [--project-name N]
            [--default-target T] [--no-git-init] [--non-interactive]
valved connect [<component>]
valved plan <goal> [--refine <plan_id>] [--pipeline <name>]
            [--table T] [--database D] [--schema S] [-q]
valved build <plan_id> [--force] [--table T] [--database D] [--schema S] [-y] [-q]
valved plan-and-build <goal> [...]
valved run <pipeline> [--target T] [--watch]
valved runs [--recovery]
valved logs <run_id>
valved deploy <pipeline> [--handoff files|commit|push|pr] [--amend] [--draft]
            [--reconcile-pins] [--investigation <id>] [--target T] [--yes]

plan turns intent into a reviewable plan; --refine <plan_id> iterates on a draft.
build runs the build agent and verifies by executing; output lands in the working tree.
deploy promotes built code via a configurable handoff (default pr), with linked PRs across repos.

Investigate

valved ask <question> [--pipeline N] [--target T] [--output text|json] [--watch/--no-watch]
valved asks list [--since <dur>] [--pipeline N] [--limit N]
valved asks show <ask_id> [--include-trace]
valved investigations list [--status proposed|resolved|dismissed] [--since <dur>]
valved investigations show <id> [--all-runs]
valved investigations dismiss <id> --reason "<text>"

Serving

valved serve [--port N] [--host H] [--workers N] [--no-scheduler] [--no-reaper] [--no-archiver]
valved worker [--workers N]
valved mcp-serve [--transport stdio|http] [--port N] [--host H]
            [--server-url URL] [--token T] [--log-level LEVEL]

Schedule (live data — no deploy)

valved schedule list
valved schedule show <pipeline>
valved schedule pause  <pipeline> [--reason "<text>"]
valved schedule resume <pipeline> [--reason "<text>"]
valved schedule set-cron <pipeline> "<cron>" [--timezone TZ] [--target-pipeline N] [--reason "<text>"]
valved schedule reseed <pipeline>

Pipelines, EL, components, targets

valved pipelines list [--status S]
valved pipelines show <name>
valved pipelines validate [<name>]
valved pipelines diff <name> --against <build_id>

valved el run <name> [--target T] [--watch] [--no-auto-fix] [--max-fix-attempts N]
valved el list [--target T]
valved el verify <name> [--target T] [--no-smoke-test]

valved component <name> --separate-remote <url> [--ref <pin> | --branch <name>]
valved component <name> --separate-local <path>
valved component <name> --same-repo
valved components show [<name>]

valved target create|list|show|rename|delete <name> [...]

Extensibility

valved agents list|show|create <name> [--template <existing>]
valved skills list|show <name>
valved skills test <name> [--args '<json>']
valved mcp-servers list
valved mcp-servers add <name> --command "<cmd>" | --url <url>
valved mcp-servers remove <name>

A user agent at valved/agents/<name>.md overrides a built-in of the same name.

Ops

valved memory show [<file>] [--pipeline N]
valved memory edit <file> [--direct]
valved memory append-decision "<title>" [--body "<text>"] [--reviewers a@,b@]
valved memory refresh [--backend dbt|dlt]

valved metrics costs|runs|agents [--since <dur>]

valved docs serve [--host H] [--port N] [--watch] [--no-auto-regen]
valved docs regen [--page <name>]
valved docs open

valved auth status        # model-provider auth mode (never a secret)
valved auth login         # mint a Claude-subscription OAuth token
valved auth rotate        # mint a new REST/MCP API bearer token → .valved/token

valved version

Environment variables

Var	Purpose
`DATABASE_URL`	Postgres connection string for the state store.
`ANTHROPIC_API_KEY` / OAuth	Model-provider credentials (never passed into the sandboxed `bash` tool).
`VALVED_API_TOKEN`	Bearer token for REST/MCP.
`VALVED_SERVER_URL`	Default for `--server-url`.
`VALVED_TARGET`	Default active target.
`VALVED_NO_DOTENV`	Set to `1` to disable `.env` auto-loading.