CLI

puppi builds a project, deploys it, runs it, and reads what the engine recorded. Inside this repository, run it as pnpm exec puppi.

Choose an environment

Flag or variable	Meaning
--env <name>, PUPPI_ENV	The environment. Required for deploy, run, status, assets, logs, lineage, and rollback, and for env subcommands other than list and create.
--engine-url, PUPPI_ENGINE_URL	Engine base URL. Default http://127.0.0.1:4000.
PUPPI_API_TOKEN	Bearer token. The compose stack uses dev.
--dir <path>	Project directory. Default .. Used by commands that build or read the project.
--json	Print the engine’s JSON. Honored by dev, doctor, run (including --local), status, assets, logs, lineage, rollback, place, and env.

Exit codes: 0 when the command succeeded, 2 for a usage error, 1 when the engine refused the request or the run is one you should look at. A run exits 1 when it did not succeed, when an asset was blocked by an upstream, or when a latest materialization in the plan is quarantined.

A manual puppi run plans the whole active graph. Naming one asset, or passing --upstream / --downstream, is a usage error. To run one asset on your machine, use puppi run --local.

Create a project

puppi init [dir]

Writes a project that defines two assets, example/people and core/person.

Flag	Meaning
--type <type>	Connection type in the scaffold. Default postgres.
--template <name>	Copy hello, atlas, or pokedex from this checkout instead of the scaffold.
--force	Overwrite files that already exist.

Files, when not using a template: puppi.config.ts, src/pipeline.ts, bindings.local.json, package.json, tsconfig.json, .gitignore. The scaffold’s next step is puppi run --local example/people.

puppi build

Writes bundle.js and manifest.json into out, and puppi-env.d.ts next to the config. Prints each asset, its role, and its dependencies. See Bundle.

puppi connector new <type> [dir]

Writes a connector package. --force overwrites. See Create a connector.

Start a local engine

puppi dev

Starts the compose stack (docker compose up -d), waits for /health, and creates the environment named in bindings.local.json (or --env / PUPPI_ENV). Writes that file’s bindings and secrets. Running it again is safe.

Flag	Meaning
--no-up	Use an engine that is already running.
--compose <file>	Compose file. Default: the nearest compose.yaml at or above the project.
--timeout <seconds>	How long to wait for /health. Default 180.

When dev starts the stack itself, bindings resolve to the compose service name (postgres for the database host), unless that variable is already set in your shell.

puppi doctor

Reports the prerequisites for a first run and continues after a failure. Accepts --compose and --timeout.

Deploy and run

puppi deploy

Builds, uploads the bundle when the engine does not have it, ingests the manifest, and activates. See Deploy and rollback.

Flag	Meaning
--no-activate	Store the deployment and leave the active pointer.
--allow-contract-change <key>	Repeat for each asset whose schema change a strict environment must accept.

puppi run

Starts a run of the whole active graph, waits, and prints each attempt. The engine answers with 202. The CLI polls until the run settles, up to 15 minutes.

Flag	Meaning
--force	Bypass the staleness gate.
--no-wait	Print the run id and return.

puppi run --local <key>

Runs one producer in a local process. It uses the real adapters from bindings.local.json and writes nothing. See the quickstart.

Flag	Meaning
--limit <n>	Rows to print. Default 10. 0 is allowed.
--input <key>=<table>	Repeat. Physical table for one ctx.input(). A model’s inputs have no default.
--inputs-from <env>	Take each input’s table from that environment’s latest. A matching --input wins.

puppi status

Prints the latest run in the environment, per attempt. --run <id> selects one run.

puppi assets [key]

Prints every asset, or one asset’s definition, staleness, and materialization history.

puppi logs <run-id>

Prints each attempt’s status, step timings, error, and ctx.log lines.

puppi lineage <key>

Prints the materialization tree behind the asset’s latest. See Lineage.

puppi rollback <key>

Moves latest to an earlier materialization. --to <materialization-id> selects it. See Deploy and rollback.

Manage environments

puppi dev is the short path. These commands are the same writes, one at a time.

puppi env list

Prints every environment: kind, storage prefix, active deployment, and whether schedules are paused.

puppi env create <name>

Creates an environment. --executor local|remote is required when the name is new. Creating an existing name changes nothing, except that a different --executor updates placement.

Flag	Meaning
--executor local|remote	Where attempts run.
--storage-prefix <p>	Prefix for stored rows. Default: the name, with non-alphanumeric runs turned into _.
--kind preview	preview or persistent. Default persistent.

puppi place <local|remote>

Sets that executor on every environment.

puppi env show

Prints the environment, its bindings, and its secret names. Values are omitted.

puppi env bind <connection>

Flag	Meaning
--config '<json>'	Binding config. A JSON object. Default {}.
--secret-ref <field>=<secret>	Repeat. Maps a secret field to a secret name.
--mode <mode>	Default live. read_only makes ctx.emit fail for assets stored on this binding.

puppi env unbind <connection>

Removes one binding.

puppi env secret <name>

Flag	Meaning
--value <v>	The secret value.
--from-env <VAR>	Read the value from that environment variable in the shell that runs the CLI.
--forget	Delete the secret.

The command prints the backend and the version. It omits the value.

puppi env pause and puppi env resume

Pause stops schedules. Manual runs still start. Resume lets schedules fire again.