---
title: CLI Usage
description: Learn how to use the Capawesome Cloud CLI — command anatomy, global flags, JSON output, exit codes, and the doctor command.
---

# 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](scripting.md).

## 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](commands.md).

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](authentication.md). |
| `--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:

```bash
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](scripting.md) 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](scripting.md) 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:

```bash
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:

```bash
npx @capawesome/cli doctor
```

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

## Next steps

- [Command reference](commands.md) — every command and its options.
- [Examples](examples.md) — practical recipes for builds, Live Updates, and CI.
- [Scripting](scripting.md) — automate the CLI in scripts and CI.
- [Authentication](authentication.md) — log in or use a token.