Skip to Content
Puppi
Reference

CLI

Build, deploy, run, and inspect a pipeline from the terminal.

puppi builds a project, deploys it, runs it, and reads what the engine recorded. Install the CLI as in the quickstart.

Choose an environment

Flag or variableMeaning
--env <name>, PUPPI_ENVThe environment. deploy, run, and status use default when both are omitted. Required for assets, logs, lineage, rollback, and deployments, and for env subcommands other than list and create.
--engine-url, PUPPI_ENGINE_URLEngine base URL. Default https://app.puppi.dev.
--dir <path>Project directory. Default .. Used by commands that build or read the project.
--jsonPrint the engine’s JSON. Honored by doctor, whoami, logout, deploy, deployments, activate, run, try, status, assets, logs, lineage, rollback, place, env, keys, and worker.

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. puppi run --wait exits 1 when the run did not succeed, when an asset was blocked by an upstream, or when a latest materialization in the plan is quarantined. puppi run --wait --timeout exits 3 when the deadline passes and the run is still going.

puppi run --local is gone. Run one producer with puppi try <key>. Naming one asset, or passing --local, --upstream, --downstream, or --no-wait, exits 2.

Log in

puppi login

Requests a device code, prints it with the confirmation URL, and opens that page when a browser can be launched. --no-browser skips the launch. After you approve the code, the CLI stores the API key in ~/.config/puppi/config.json ($XDG_CONFIG_HOME/puppi/config.json when that variable is set). The file mode is 0600. The key is not printed.

--engine-url or PUPPI_ENGINE_URL selects the server. The default is https://app.puppi.dev.

puppi whoami

Prints the user and tenant for the stored key. The key is sent only when that server has the same origin as the one saved at login. --json prints the engine’s payload plus server.

puppi logout

Revokes the stored key and deletes the file. A key that the server already rejects is still deleted locally.

Create a project

puppi init [dir]

Writes a project that defines two assets, example/people and core/person. The connection is files (@puppi/adapter-filesystem). Rows are Parquet. bindings.local.json sets root to out/files.

FlagMeaning
--forceOverwrite files that already exist.

Files: README.md, puppi.config.ts, src/pipeline.ts, bindings.local.json, package.json, tsconfig.json, .gitignore. package.json depends on @puppi/sdk. @puppi/adapter-filesystem, @puppi/cli, and typescript are devDependencies. The next commands are puppi login, puppi deploy, puppi run, and puppi status.

puppi build

Writes bundle.js and manifest.json into the directory out names, and puppi-env.d.ts next to the config. puppi init sets out to out. When out is omitted, the directory is dist. It then runs the project’s installed tsc --noEmit against tsconfig.json. A type error fails the build and the command prints the compiler’s output, so puppi deploy uploads nothing. No tsconfig.json, or TypeScript not installed, fails the build; the message names which one and how to add it. The command 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.

Check the engine

puppi doctor

Reports whether the engine answers, the token is accepted, the database read succeeds, and the engine’s SDK matches this project. It also checks that puppi.config.ts is in --dir. A failure does not stop the rest of the report. Exit 1 when any check fails.

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.

FlagMeaning
--no-activateStore the deployment and leave the active pointer.
--allow-contract-change <key>Repeat for each asset whose schema change a strict environment must accept.
--signing-key <file>Sign the bundle digest with this key. See Signing.

When a signing key is configured, the command signs the bundle digest. A warning that no connected worker trusts that key is printed and the command still exits 0 when the deployment is ready. See Deploy and rollback.

When --env and PUPPI_ENV are omitted, puppi deploy uses the environment default. The first deploy creates it with executor hosted and storage prefix default. A later deploy reuses that environment and leaves its executor.

puppi deployments

Prints this environment’s deployments, newest first. The active one is marked active. The command needs --env or PUPPI_ENV. It does not fall back to default.

puppi activate <id>

POST /deployments/:id/activate. Makes that deployment the active one and prints activated <id>. The id selects the deployment. The command does not take --env. Data rollback stays puppi rollback.

puppi run

Starts a run of the whole active graph, prints the run id, and exits 0. The engine answers with 202. Follow the run with puppi status --run <id>. With no --env and no PUPPI_ENV, the command uses default. It does not create that environment. puppi deploy does.

FlagMeaning
--forceBypass the staleness gate.
--waitPoll until the run settles, print attempt transitions, then the summary table. Exit 1 when the run did not succeed.
--timeout <seconds>With --wait, stop polling after this many seconds. Exit 3 and print how to follow the run, which keeps going.

puppi try <key>

Runs one producer on this machine. Adapters and secrets come from bindings.local.json. The command prints the rows, the observed columns, and the schema-contract verdict, then Ran locally. Nothing was written. It writes no materialization, moves no latest, and records no lineage. It does not set an environment’s executor. See the quickstart.

FlagMeaning
--limit <n>Rows to print. Default 10. 0 is allowed. A value that is not a whole number exits 2.
--inputs-from <env>Read each dependency’s latest materialization from that environment. Overrides --env and PUPPI_ENV.

With no --inputs-from, no --env, and no PUPPI_ENV, an asset that declares a dependency exits 2. The message says it needs a latest materialization and names --inputs-from. An asset with no dependencies runs, and the producer gets no inputs. puppi try does not use default on its own. A dependency with no latest in the named environment exits 2, and the message names the asset and the environment. Exit 1 when the contract fails, a blocking check fails, or a check throws.

puppi status

Prints the latest run in the environment, per attempt. --run <id> selects one run. With no --env and no PUPPI_ENV, the command uses default.

puppi assets [key]

Prints every asset, or one asset’s definition, staleness, and materialization history. The next-run column is UTC and keeps the zone, for example 2026-10-19T23:00:00Z. With no active deployment the command prints No active deployment in <env>. Run puppi deploy. instead of an empty table.

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. The command needs --env or PUPPI_ENV. It does not fall back to default. See Deploy and rollback.

Manage environments

These commands write an environment, one fact 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 is required when the name is new. Creating an existing name changes nothing, except that a different --executor updates placement.

Choose hosted for Puppi-managed execution or remote for your worker pool. Pass one word. The CLI also accepts the word local. A public API request that selects local is 403 local_not_allowed and writes nothing.

FlagMeaning
--executor <hosted or remote>Where attempts run. Pass one word. local is refused by the public API with 403 local_not_allowed.
--storage-prefix <p>Prefix for stored rows. Default: the name, with non-alphanumeric runs turned into _.
--kind previewpreview or persistent. Default persistent.
--signing-key <file>Sign the name and storage prefix of a new environment. An existing environment is left as it is. The command exits 2 before it changes placement only when a key is configured, the target placement checks signatures, and the stored key is not that key. Today that placement is remote.

puppi place hosted

Sets hosted on every environment. puppi place remote sets remote. puppi place local is refused with 403 local_not_allowed.

puppi env show

Prints the engine URL, the environment, its placement (executor), its bindings, and its secrets. Values are omitted.

The first lines name the engine you are talking to, the executor, whether the environment is signed and by which public key, and the same for the active deployment. Each binding row includes its signing key, or unsigned. Each secret row includes its backend, and a line under the table says what that backend stores. The value is not printed. A worker-held secret shows version on worker. --json adds the active deployment object beside the environment, bindings, and secrets.

puppi env bind <connection>

FlagMeaning
--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.
--type <type>Must match the type declared for this connection in puppi.config.ts. A connection the project does not declare cannot be signed.
--signing-key <file>Sign this binding. See Signing.

puppi env unbind <connection>

Removes one binding.

puppi env secret <name>

FlagMeaning
--value <v>The secret value.
--from-env <VAR>Read the value from that environment variable in the shell that runs the CLI. An unset or empty variable is a usage error.
--forgetDelete the secret.
--on-workerDeclare the name and store no value. The worker reads the value from its own machine. Combining this with --value, --from-env, or --forget is a usage error.

The command prints the backend and the version. It omits the value. A worker-held secret reports version on worker. Declaring one deletes a value the engine already held for that name.

puppi env webhook

One https URL for failure alerts. set --url <https://…> creates it or replaces the URL. The signing secret is printed once, on create. --rotate prints a new secret. --disable saves the URL and sends nothing. test sends one alert.test event. rm removes the webhook.

The payload and the Puppi-Signature header are in Environments.

puppi env pause and puppi env resume

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

Signing

puppi deploy, puppi env create, and puppi env bind sign when a key is configured. The private key is one line, ed25519: and the base64 of the 32-byte seed. The public key, which a worker trusts, is ed25519: and the base64 of the raw 32-byte public key.

SourceWhen it is used
PUPPI_SIGNING_KEYFirst. CI sets this and the CLI does not read a file.
--signing-key <file>The file you named. Missing is an error.
PUPPI_SIGNING_KEY_FILEThat path. Missing is an error.
puppi-signing-key in --dirWhen the file exists. Absent means the command does not sign. When the executor is hosted and the row has no signature, the command prints unsigned. A hosted executor does not check signatures. Otherwise a row with no signature prints NOT SIGNED and exits 0. Signing is what a remote worker checks. An unchanged re-bind keeps the stored signature. A re-bind that would change config under an existing signature exits 2.

puppi keys create

Writes a new key, or prints the public key for PUPPI_SIGNING_KEY when that variable is set. Standard output is the public key. The path and the fingerprint go to standard error.

FlagMeaning
--out <file>Where to write the private key. Default puppi-signing-key in --dir. With PUPPI_SIGNING_KEY set, the command writes only when you pass --out.
--forceOverwrite a file that already exists.

--json prints public_key, fingerprint, and path.

Workers

The container on a machine you keep is Workers. These commands talk to the engine, and start is the development path.

puppi worker token create <name>

Creates a pool token and prints it once, on its own line. The note on standard error carries the id and the name.

puppi worker token list

Prints id, name, and last use. The plaintext is not listed.

puppi worker token revoke <id>

Revokes the token and closes the sockets that presented it.

puppi worker list

Prints the queue depth and each connected worker: id, free slots, version, residency, trusted-key fingerprints, and any declared worker secret that worker did not report. --env (or PUPPI_ENV) limits the comparison to that environment. With neither, the comparison is every environment. --json is the engine’s pool object plus missing_secrets on each worker.

puppi worker start [--slots N]

Runs the pool worker in the foreground until it exits. --slots sets PUPPI_WORKER_SLOTS and has to be a positive integer. The command needs PUPPI_WORKER_TOKEN or PUPPI_WORKER_TOKEN_FILE, and it passes the resolved engine URL as PUPPI_ENGINE_URL.

This is not the container you run on a droplet. See Workers.