CLI reference

Deployxa CLI reference

Every command in @deployxa/cli 1.0.4, grouped by what it does. Commands that act on a project use the folder you run them in, linked through .deployxa/config.json.

shell

$ npm install -g @deployxa/cli
$ deployxa login
$ deployxa deploy

Usage

shell

deployxa <command> [subcommand] [arguments] [flags]

Run deployxa help for the command list and deployxa <command> --help for usage of the commands that document it (login, logout, whoami, projects, deploy, status, rollback, env, domains, logs, members, organizations, token, telemetry, config, plugins).

Global flags and settings

Flag / variable	Effect
`--json`	Prints raw JSON instead of tables. Honored by whoami, organizations, projects, deploy, status, deployments, domains list, metrics and the billing commands.
`--help, -h`	Prints usage for the command.
`DEPLOYXA_TOKEN`	Auth token sent with every request. Overrides the stored login. Sent verbatim as the Authorization header, so include the "Bearer " prefix.
`DEPLOYXA_API_URL`	Control plane URL. Defaults to https://api.deployxa.com. Overrides the api-url config key.
`deployxa config set output-format json`	Makes --json the default for every command that supports it.

Files the CLI writes

Path	Contents
`~/.deployxa/auth.json`	Your token, encrypted with a key derived from this machine’s hostname and user. Removed by deployxa logout.
`~/.deployxa/cli-config.json`	CLI settings from deployxa config, telemetry and plugins.
`./.deployxa/config.json`	Project link for this folder: projectId, organization, branch. Commit it if your team shares the link, or add it to .gitignore.
`./.env.local`	Written by deployxa env pull.

All commands

Authentication

Command	Description
`deployxa login [--token <token>]`	Browser sign-in through a local server on port 5678, or save a token non-interactively with --token.
`deployxa logout`	Deletes the stored credentials file (~/.deployxa/auth.json).
`deployxa whoami [--json]`	Shows the signed-in user, active organization and plan.
`deployxa organizations [--json]`	Lists every organization you belong to, with your role and its plan.
`deployxa token create`	Generates a long-lived CI/CD token (valid 365 days) and prints it once.

Projects

Command	Description
`deployxa projects [list \| create] [--json]`	Lists projects in the active organization; "create" runs the init wizard. Alias: project.
`deployxa init`	Interactive wizard: creates a project and optionally links the current folder.
`deployxa link`	Pick an existing project and link the current folder (.deployxa/config.json).
`deployxa create <template>`	Scaffolds a starter: nextjs, express, fastapi, vue, nuxt, sveltekit or django.
`deployxa team`	Shows organization settings: plan, SSO, branch protection, env prefix and IP rules.
`deployxa members [list \| invite]`	Lists organization members, or invites one (ADMIN, DEVELOPER or VIEWER). Alias: member.
`deployxa invite`	Interactive prompt to invite a member by email and role.

Deployments

Command	Description
`deployxa deploy [projectId] [path] [--watch] [--json]`	Packages the folder (or a .zip/.tar.gz), uploads it and tracks the build. Creates and links a project if none is linked.
`deployxa redeploy`	Queues a new deployment of the linked project from its previous source.
`deployxa cancel`	Stops the first queued, building or deploying deployment of the linked project.
`deployxa status [--json]`	Status, URL and start time of the latest deployment.
`deployxa deployments [--json]`	Deployment history: version, status, age, Preview or Production.
`deployxa promote`	Promotes the latest successful preview deployment to production.
`deployxa rollback [deploymentId \| latest \| previous \| production]`	Re-activates an earlier successful deployment without rebuilding. No argument opens a picker.
`deployxa open`	Opens the linked project’s live URL in your browser.
`deployxa restart`	Queues a restart of the running workload.
`deployxa scale [replicas]`	Shows autoscaling settings, or pins min and max replicas to one number.
`deployxa cache clear`	Purges the remote build cache for the linked project.
`deployxa artifacts`	Lists build artifacts and downloads the one you pick into the current folder.

Environment

Command	Description
`deployxa env list \| set <KEY> <VALUE> \| pull \| push \| remove <KEY>`	Manage project environment variables. "add" is an alias of "set".
`deployxa secrets`	Lists variable names only (values hidden).

Domains

Command	Description
`deployxa domains [list \| add <domain> \| remove <domain>] [--json]`	Manage custom domains on the linked project. Alias: domain.
`deployxa dns`	Shows each domain as Waiting, Verified or SSL Active.

Monitoring

Command	Description
`deployxa logs [deploymentId] [--live \| -l]`	Prints logs for a deployment (latest by default); --live polls every second.
`deployxa metrics [--json]`	CPU, RAM limit, replicas, requests, latency and bandwidth for the linked project.
`deployxa inspect`	Framework, image name, container ID and port of the latest deployment.
`deployxa history`	Recent deploy, rollback and env change events for the project.

Diagnostics

Command	Description
`deployxa doctor`	Checks Docker, Git, Node, internet, stored token, API reachability, project link and folder permissions.
`deployxa validate`	Pre-flight checks: package.json or index.html, clean git tree, .env files, project link.
`deployxa detect`	Prints the framework, runtime, package manager and build/start commands the CLI detects locally.
`deployxa build`	Runs the detected build command locally to catch errors before you upload.
`deployxa diff`	Lists changed files from git status before you deploy.
`deployxa ai diagnose \| optimize`	Runs the AI advisor against the linked project.
`deployxa shell`	Runs docker exec into the project container. Alias: ssh. See Power tools for the limits.

Billing

Command	Description
`deployxa billing [--json]`	Active plan, credit balance and this month’s cost.
`deployxa usage [--json]`	Metered CPU hours, RAM GB-hours, bandwidth, build minutes and storage.
`deployxa costs [--json]`	Spend today, yesterday, this month and projected, with a per-resource breakdown.
`deployxa credits [--json]`	Credit balance, grace-period status and recent transactions.
`deployxa topup [amountCents]`	Prints a checkout URL to add credits (default 2000 cents).
`deployxa invoices [--json]`	Lists invoices with plan, total and status.
`deployxa budget [set <amountCents> <daily\|weekly\|monthly>] [--json]`	Lists spending budgets or sets one.
`deployxa estimate [--json]`	Estimates hourly and monthly cost from the project’s limits and databases.
`deployxa alerts [--json]`	Lists active billing and spending alerts.

CLI

Command	Description
`deployxa config [set <key> <value>]`	Shows or sets api-url, default-region, output-format (default\|json) and organization.
`deployxa completion <bash \| zsh \| fish \| powershell>`	Prints a shell completion script.
`deployxa telemetry [enable \| disable \| status]`	Toggles anonymous telemetry in the local CLI config.
`deployxa plugins list \| install <name>`	Marks sentry, slack, datadog or github-actions as installed in local config. Alias: plugin.
`deployxa notifications`	Prints recent project notifications.
`deployxa releases`	Prints the CLI release notes.
`deployxa interactive (-i)`	Opens the menu-driven mode. Running deployxa with no arguments does the same in an unlinked folder.
`deployxa version (-v)`	Prints the CLI version.
`deployxa update`	Prints the installed version. To upgrade, reinstall with npm (see Installation).
`deployxa help (-h)`	Prints the command list. Most commands also accept --help.

Exit codes

Commands exit 0 on success and 1 on any error, including a failed deployment during deployxa deploy, so you can chain them in CI. API errors print as ❌ [CLI Error] …; a 401 means your session expired (run deployxa login) and a 429 means you hit the rate limit.

Not in the CLI: There is no --prod flag, no deployxa env set --environment, and no command to verify a domain or edit DNS. Do those in the dashboard.

Topic guides: Installation, Authentication, Projects, Deployments, Domains, Logs & metrics, Power tools.

By Framework

By Use Case

Compare