Skip to content

Usage

This page covers how every CLI command works — the command pattern, the flags that apply everywhere, how to read output, and how to diagnose problems. For automating the CLI in CI, see Scripting.

Running commands

Commands follow the pattern apps:<resource>:<action> — for example apps:builds:create or apps:channels:list. The resource is what you're acting on (builds, channels, deployments, …) and the action is what you're doing to it (create, list, get, …). Browse them all in the Command reference.

Most commands prompt for any required values you don't provide, so you can run them interactively and fill in the blanks. Pass those values as flags instead to run non-interactively — which is what you'll do in scripts and CI.

Global flags

These flags work across commands:

Flag Description
--app-id The target app ID (skips the app prompt).
--token An API token for non-interactive authentication.
--yes Skip confirmation prompts (for scripts and CI).
--json Output machine-readable JSON instead of human-readable text.
--help Show help for any command.

For commands that act on a specific app, pass --app-id to skip the interactive app picker — essential in CI, where there's nobody to answer the prompt.

Getting help

Show the available commands, or help for a specific one:

npx @capawesome/cli --help
npx @capawesome/cli apps:builds:create --help

--help lists every flag a command accepts, so it's the fastest way to discover options without leaving the terminal.

JSON output

Add --json to any command to get structured output you can parse in scripts — for example, to read a new build's ID out of apps:builds:create --json and use it in a later step. Note that commands which stream progress print the JSON only at the end, so parsing them needs a little care. See Scripting for the details and recipes.

Exit codes

The CLI exits with status code 0 on success and a non-zero code on failure. In a CI pipeline this means a failed command stops the job by default — no extra error handling required to fail the build when, say, an upload or submission doesn't go through. See Scripting for the exceptions, such as --detached builds.

Connecting through a proxy

If your network routes outbound traffic through a proxy — common in corporate or CI environments — the CLI honors the standard proxy environment variables. Set the relevant one before running a command:

export HTTPS_PROXY=http://proxy.example.com:8080

The CLI picks the proxy based on the protocol of the request it's making:

Variable Used for
HTTPS_PROXY (or https_proxy) https:// requests — what you'll normally need.
HTTP_PROXY (or http_proxy) http:// requests.

The proxy itself can be reached over either protocol, so an HTTP proxy can tunnel HTTPS requests (HTTPS_PROXY=http://proxy.example.com:8080 is valid). For a proxy that requires credentials, include them in the URL: http://user:password@proxy.example.com:8080. If the variable for a request's protocol isn't set, the CLI connects directly.

Doctor

Diagnose your environment and authentication — Node.js version, login state, and connectivity — with:

npx @capawesome/cli doctor

This is the first thing to run when a command behaves unexpectedly.

Next steps