CLI reference
Every command of the zitadel CLI, with its flags and examples, generated from the commands the CLI defines. Run a command with npx @zitadel/cli@latest <command>; --help after it prints the same for the version you run.
In a script or as a coding agent, pass --non-interactive --json: every command then prints one JSON envelope, which Agent setup describes.
Global flags
Every command takes these.
| Flag | Description |
|---|---|
--json | Format output as json. |
-c, --cwd <value> | Project directory to operate on. |
-s, --server <value> | Override the resolved server URL. |
-n, --non-interactive | Disable prompts. Required when scripting or running as an agent. |
--dry-run | Preview without mutating files or the platform. |
-v, --verbose | Verbose logging. |
--debug | Debug logging. |
--[no-]color | Colorize human output. Disable with --no-color; NO_COLOR and FORCE_COLOR are honored too. On by default. |
--[no-]telemetry | Send anonymous usage analytics. Disable with --no-telemetry. On by default. |
Environment variables
These set what a global flag sets, for every command.
| Variable | Flag | Description | Precedence |
|---|---|---|---|
ZITADEL_API_BASE | --server | The server URL, or local, as --server takes it. | --server wins over it, and it wins over server in zitadel.json. |
NO_COLOR | --color | A non-empty value turns color off, as --no-color does (https://no-color.org). | Turns color off even with --color or FORCE_COLOR. |
FORCE_COLOR | --color | Turns color on where it would be off, such as in a pipe, as --color does. | --no-color and NO_COLOR win over it. |
DO_NOT_TRACK | --telemetry | Any value but 0 or an empty one turns telemetry off (https://consoledonottrack.com). | Turns telemetry off even with --telemetry. |
ZITADEL_TELEMETRY | --telemetry | An empty value or one of 0, false, off, no turns telemetry off. | Turns telemetry off even with --telemetry. |
Exit codes
A command that succeeds, or skips because there is nothing to do, exits 0. One that fails exits with the code of the error its envelope names in code.
| Exit code | Error codes |
|---|---|
0 | E_ALREADY_INIT |
1 | E_AUTH |
2 | E_NOT_IMPLEMENTED |
3 | E_FRAMEWORK_NOT_DETECTED, E_UNSUPPORTED_PROJECT_SHAPE, E_VALIDATION, E_CREDENTIAL_MISSING |
4 | E_NETWORK, E_LOCAL_SERVER_NOT_RUNNING, E_NOT_FOUND |
5 | E_CONFLICT, E_PORT_IN_USE |
130 | E_CANCELLED |
Getting started
| Command | Description |
|---|---|
setup | Create a Zitadel project and scaffold local auth. An interactive setup ends with a note about the Zitadel agent skills, shown once per machine; set NO_SKILLS_PROMPT=1 to hide it. |
start | Start a local Zitadel server. |
status | Summarize the local Zitadel server and project state. |
claim | Claim this project to make it permanent. Opens a browser to create an account or sign in. |
skills add | Add the Zitadel agent skills to this project. |
Local development
| Command | Description |
|---|---|
console | Open the local console, signed in as the local admin. |
logs | Show local Zitadel server logs. |
stop | Stop the local Zitadel server. |
reset | Delete the local Zitadel server runtime and data. |
eject | Remove managed files and local Zitadel state. |
Users and teams
| Command | Description |
|---|---|
users create | Create a user. |
users delete | Delete a user by id. |
users get | Get one user by id. |
users list | List users. |
users update | Update a user by id. |
teams create | Create a team. |
teams deactivate | Deactivate a team by id. |
teams get | Get one team by id. |
teams list | List teams. |
teams update | Update a team by id. |
grants create | Create a grant. |
grants delete | Delete a grant by id. |
grants get | Get one grant by id. |
grants list | List grants. |
Authentication
| Command | Description |
|---|---|
auth-method passkey disable | Disable passkey sign-in for a user schema. |
auth-method passkey enable | Enable passkey sign-in for a user schema. |
auth-method password disable | Disable password sign-in for a user schema. |
auth-method password enable | Enable password sign-in for a user schema. |
auth-method sso disable | Remove an identity provider from a user schema. |
auth-method sso enable | Add an identity provider to a user schema. |
idps create | Create an identity provider connection. |
idps get | Get one identity provider connection by id. |
idps list | List idps. |
sessions get | Get one session by id. |
sessions list | List sessions. |
sessions revoke | Revoke a session by id. |
Configuration and releases
| Command | Description |
|---|---|
deploy | Apply your local configuration to Zitadel. |
preview | Deploy a release from .zitadel/ to a pull-request build's preview URLs. |
pull | Rebuild your .zitadel/ files from a release. |
branding eject | Take ownership of the login template: scaffold .zitadel/branding/ from a shipped design. |
branding get | Get one branding revision by id. |
branding list | List branding. |
deployment create | Deploy an existing release to the project's origins. |
deployment get | Read one deployment by id. |
deployment list | List the project's deployments, newest first. |
deployment rollback | Roll back to an earlier deployment. |
env | Show which server and project resolve, and where each value came from. |
env add | Bind an environment to a project, creating the project if needed. |
env list | List the environments bound in this directory's .env files. |
flow-definitions get | Get one flow definition by flow name (newest revision) or revision id. |
flow-definitions list | List flow-definitions. |
origin add | Add an origin pattern to the project. |
origin list | List the origin patterns on the project. |
origin rm | Remove an origin pattern from the project. |
policies get | Get one policy by policy id or operation. |
policies list | List policies. |
policies test | Run the test cases in .zitadel/policies/ against the policies |
preview list | List the project's live previews, newest first. |
preview rm | Remove a live preview from the project. |
projects get | Get one project by id. |
projects list | List projects. |
projects update | Update a project by id. |
release create | Build a release from .zitadel/ without deploying it. |
release get | Get one release by id. |
release list | List release. |
release revoke | Revoke a release so its content is never served again. |
schemas get | Get one schema by object type (current revision) or revision id. |
schemas list | List schemas. |
variable get | Get one variable from the project. |
variable list | List the variables entered on the project. |
variable resolve | Show the variables the live deployment froze for a target. |
variable rm | Remove one variable from the project. |
variable set | Set one variable on the project. |
Diagnostics and utilities
| Command | Description |
|---|---|
doctor | Verify local runtime and project state. |
api | Call any operation of the Zitadel API, with this project's server and project secret. |
api ls | List the operations of the Zitadel API that zitadel api calls. |
events get | Get one event by id. |
events list | List events. |
resources | List the resources this CLI manages. |
npx @zitadel/cli@latest --help also lists oclif's own commands, such as help and version, under Diagnostics and utilities.
Was this helpful?