Overview
What every command shares - the API key, flags, output, exit codes, confirmations and waits.
Sign in with an API key
Every command that talks to the platform needs your tenant API key. Run ignitify login once on each machine, or set the IGNITIFY_API_KEY environment variable, which wins.
$ ignitify task:listError: Not signed in. Run 'ignitify login', or set the IGNITIFY_API_KEY environment variable.
Never put the key in task.yaml. The CLI sends it as a bearer token with each request.
Each command page shows a badge. It says if the command needs the key or can run offline.
Environment variables
The --dir flag wins over the variable. The variable wins over the default.
| Name | Meaning |
|---|---|
IGNITIFY_API_KEY | Your tenant API key. |
IGNITIFY_TASKS_DIR | Folder that holds your task folders. Default: tasks, from where you run the command. |
Global flags
These flags work on every command.
$ ignitify task:list --limt 5Error: unknown flag --limt for task:list. Did you mean --limit?
| Name | Meaning |
|---|---|
--json | Print one JSON document on stdout. Messages go to stderr. |
--help | Print the usage of the command and stop. |
Short flags
There are three short flags. No other short flag exists.
| Name | Meaning |
|---|---|
-h | The same as --help. Works anywhere. |
-y | The same as --yes. Works anywhere, on commands that have --yes. |
-v | The same as --version. Works only as the first word. |
A flag or an argument that a command does not take is an error, not ignored.
Output
A command prints its result on stdout. Progress lines, notes, warnings and questions go to stderr.
Colour is used only when the output is a terminal. A progress line is drawn only on a terminal, and a pipe gets one line per phase.
The --json rule
With --json, a command that succeeds prints exactly one JSON document on stdout, and nothing else. The keys are snake_case.
$ ignitify task:validate image-resize --json{
"task_id": "image-resize",
"valid": true
}A command with nothing to report prints a short document about its outcome, for example the schedule id and cancelled.
A command that fails prints nothing on stdout. Read the error on stderr.
One exception: task:run --wait prints the finished run even when it did not complete, because that run is the result.
Errors and the trace id
An error prints on stderr as Error: and a message.
$ ignitify hook:create dep_Hn4TqXw8Zc2P --task-name image-resizeError: API 403: {"error":"webhooks are not included in your current tier (capability 'may_use_webhooks'; deployment 019f3c24-1b05-7c9a-8e21-4d6f0b93a7e2)"}server trace id: 5d1e8c0a-4b7f-4f6e-9a21-3c0d7e5b8f12
After an error from the server, the CLI also prints server trace id: and an id. Give this id to support.
An answer that the CLI cannot explain better is shown as API, the status and the server's body.
Exit codes
A command page lists an exit code only when it differs from this table.
| Name | Meaning |
|---|---|
0 | The command did what you asked. |
1 | It did not: an error, a refusal, bad input, a declined question, or a run that did not complete under --wait. |
130 | You pressed Ctrl+C while the CLI waited. Nothing was cancelled on the server. |
Confirmations
Delete and cancel commands ask Proceed? [y/N] before they act. Only --yes skips the question.
$ ignitify run:delete run_H8kQ2mNxT4pLWill soft-delete run run_H8kQ2mNxT4pL.Error: Refusing to proceed: not a TTY. Re-run with --yes to confirm non-interactively.Aborted.
--force is different. It unlocks a refusal, for example a pinned VM, and the command still asks.
With no terminal and no --yes, the command refuses and exits 1.
Pagination
A list command returns one page. --limit sets the page size, and the server sets the default and the largest value.
For the next page, pass the id of the last row as --after-id. The --after flag is a time filter, not a cursor.
vm:list pages by boot time. Pass booted_at and vm_id of the last row as --after and --after-vm-id.
Waits
task:deploy waits up to 15 min for the build. task:run --wait waits up to 30 min for the run.
$ ignitify task:run image-resize --waitMonthly egress: 0 B of 100.0 GB used (0%), 100.0 GB leftMonthly compute: 42 s used, no monthly limitResets 2026-11-01T00:00:00.000Z · details: ignitify usageStopped waiting. The run keeps going on the server — nothing was cancelled.Check it with: ignitify run:get 019f3c27-9d63-7e48-a5b0-2f17c8d4e936
The CLI asks again with a growing pause, from 0.5 to 1 s for a deploy and from 0.5 to 3 s for a run.
When the time is up, or when you press Ctrl+C, the CLI stops waiting. It cancels nothing on the server.
A failed check is tried again. The CLI gives up after 3 failures in a row that last at least 60 s.
Timeouts and limits
A write that times out may still complete on the server. The error says so; check before you repeat it.
| Name | Meaning |
|---|---|
| Request | 120 s for each call to the server. |
| Upload | 300 s for the upload of a deploy. The task folder may hold up to 64 MiB. |
| Package review | 60 s for task:validate --review-packages. |
| Version check | 3 s for ignitify --version. |
| Payload and result | A run takes at most 10 KiB of input and gives back at most 10 KiB. |
run:get shows the first 40 lines of a result, and a failed build shows the last 30 lines of its log.
Version check
Every server answer names the oldest client that the API supports. An older client prints one warning on stderr and keeps working.
ignitify --version prints the client version and the API version.