CLI

The valved CLI is the primary surface, and the only complete one. The core loop — plan, build, deploy, run — plus the control-plane and inspection commands have REST and MCP equivalents, so the CLI is one client among several there. Project setup is not: init, connect, auth, creating or changing targets, graduating a component, and el run exist only as CLI commands, and the REST routers for targets, components, agents, skills and MCP servers are read-only. See what each surface covers.

For the full command listing, grouped by area with each command’s principal flags, see the CLI reference. This page is an orientation.

Global shape

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

• --project-dir — the project root (the directory containing valved.toml); defaults to the current directory.
• --env-file — path to a .env file; defaults to <project-dir>/.env. Valved auto-loads it on startup (existing shell vars win). Set VALVED_NO_DOTENV=1 to disable.
• --target — the active target (dev, staging, prod); overrides $VALVED_TARGET and default_target in valved.toml.

The command groups

Group	Commands	What it does
Lifecycle	init, connect, plan, build, plan-and-build, run, runs, logs, deploy	The core loop: scaffold → plan → build → run → deploy.
Investigate	ask, asks, investigations	Read-only exploration and recovery records.
Serving	serve, worker, mcp-serve	Run the control plane, standalone workers, or the MCP adapter.
Schedule	schedule list/show/pause/resume/set-cron/reseed	Mutate the live schedule (data, not code).
Pipelines & components	pipelines, el, component, components, target	Inspect and manage pipelines, EL components, and targets.
Extensibility	agents, skills, mcp-servers	Bring-your-own agents, skills, and external MCP servers.
Ops	memory, metrics, docs, auth, version	Project memory, cost/usage rollups, the static UI, credentials.

A minimal session

valved init --with-dbt
valved serve &                                    # control plane
valved plan "ingest the Stripe charges API"       # intent → plan
valved build <plan_id>                            # plan → code (verified by execution)
valved run <pipeline> --watch                     # execute against dev
valved deploy <pipeline>                           # open a reviewable PR

Every command supports --help, and that output is authoritative for flags. The CLI reference collects the command set in one page and adds the two things --help doesn’t carry: the exit codes commands return, and the environment variables Valved reads.