> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

<Note>The Stigg CLI is currently in **public beta**. Feedback and bug reports are welcome.</Note>

The Stigg CLI is a REST API wrapper for your terminal. Provision customers, manage subscriptions, report usage, check entitlements — any operation available through the Stigg API is available as a command.

<Card title="GitHub" icon="github" href="https://github.com/stiggio/stigg-cli">
  stiggio/stigg-cli
</Card>

<Steps>
  <Step title="Install">
    Install the Stigg CLI via Homebrew or Go:

    <CodeGroup>
      ```bash Homebrew theme={null}
      brew tap stiggio/tools
      brew install stigg
      ```

      ```bash Go theme={null}
      go install 'github.com/stiggio/stigg-cli/cmd/stigg@latest'
      ```
    </CodeGroup>

    Requires Go 1.22 or later for the Go install. The binary is placed in your Go bin directory (default: `$HOME/go/bin`). If `stigg` isn't found after installation, add it to your `PATH`:

    ```bash theme={null}
    export PATH="$PATH:$(go env GOPATH)/bin"
    ```
  </Step>

  <Step title="Authenticate">
    In the Stigg app, go to **Settings > API keys** and copy a key for the environment you want to use. You can provide the key in two ways:

    ```bash theme={null}
    # Set as an environment variable (recommended)
    export STIGG_API_KEY=<YOUR_API_KEY>
    stigg v1:customers list

    # Or pass it inline per command
    stigg v1:customers list --api-key '<YOUR_API_KEY>'
    ```

    For CI/CD pipelines, store the key as a secret and inject it as `STIGG_API_KEY` at runtime.

    <Warning>
      Never hard-code API keys in scripts or commit them to source control.
    </Warning>
  </Step>

  <Step title="Start using">
    Query your Stigg environment directly from the terminal:

    ```bash theme={null}
    # List all customers
    stigg v1:customers list

    # Retrieve a specific subscription
    stigg v1:subscriptions retrieve --id sub-abc123

    # Check a customer's entitlement
    stigg v1:entitlements check --customer-id cust-001 --feature-id feature-api-calls
    ```
  </Step>
</Steps>

***

## Common commands

**Read operations**

| Command                           | Description                                         |
| --------------------------------- | --------------------------------------------------- |
| `stigg v1:customers list`         | List all customers in the current environment       |
| `stigg v1:customers retrieve`     | Get details for a specific customer                 |
| `stigg v1:subscriptions list`     | List subscriptions, optionally filtered by customer |
| `stigg v1:subscriptions retrieve` | Get full details for a subscription                 |
| `stigg v1:entitlements check`     | Check a customer's access to a specific feature     |
| `stigg v1:plans list`             | List all plans in the product catalog               |

**Write operations**

| Command                            | Description                                              |
| ---------------------------------- | -------------------------------------------------------- |
| `stigg v1:customers provision`     | Create or update a customer record                       |
| `stigg v1:subscriptions provision` | Subscribe a customer to a plan                           |
| `stigg v1:subscriptions update`    | Update an existing subscription (e.g. add-on quantities) |
| `stigg v1:subscriptions cancel`    | Cancel a subscription immediately or at period end       |
| `stigg v1:usage report`            | Report metered feature usage for a customer              |
| `stigg v1:events report`           | Submit a raw usage event for aggregation                 |

Run `stigg --help` for the full command reference, or `stigg v1:<resource> --help` for flags on a specific resource.

***

## Example use-cases

**Debug a customer issue**

Check what a customer is entitled to and whether their subscription is active, without opening the Stigg console:

```bash theme={null}
stigg v1:customers retrieve --id cust-001
stigg v1:subscriptions list --customer-id cust-001
stigg v1:entitlements check --customer-id cust-001 --feature-id feature-api-calls
```

**Seed a sandbox for local development**

Provision a test customer and subscription in one shot:

```bash theme={null}
stigg v1:customers provision --customer-id cust-test-001 --email dev@example.com --name "Test User"
stigg v1:subscriptions provision --customer-id cust-test-001 --plan-id plan-pro
```

**Automate in CI/CD**

Provision test fixtures before integration tests run, then tear them down after:

```bash theme={null}
# Setup
export STIGG_API_KEY=$STIGG_SANDBOX_KEY
stigg v1:customers provision --customer-id cust-ci-$BUILD_ID --email ci@example.com
stigg v1:subscriptions provision --customer-id cust-ci-$BUILD_ID --plan-id plan-starter

# ... run tests ...

# Teardown
stigg v1:subscriptions cancel --customer-id cust-ci-$BUILD_ID --cancellation-date IMMEDIATE
```

**Report usage from a script**

Push metered usage from a batch job or cron task:

```bash theme={null}
stigg v1:usage report --customer-id cust-001 --feature-id feature-api-calls --value 150
```

***

<Card title="CLI vs MCP server" icon="arrow-right-arrow-left" href="/api-and-sdks/cli-vs-mcp">
  Not sure which tool to use? See the side-by-side comparison.
</Card>

***

## Global flags

| Flag                | Description                                                                           |
| ------------------- | ------------------------------------------------------------------------------------- |
| `--api-key`         | Stigg API key (overrides `STIGG_API_KEY`)                                             |
| `--help`            | Show command usage                                                                    |
| `--debug`           | Enable debug logging, including HTTP request/response details                         |
| `--version`, `-v`   | Show the CLI version                                                                  |
| `--base-url`        | Use a custom API backend URL                                                          |
| `--format`          | Output format: `auto`, `explore`, `json`, `jsonl`, `pretty`, `raw`, `yaml`            |
| `--format-error`    | Output format for errors: `auto`, `explore`, `json`, `jsonl`, `pretty`, `raw`, `yaml` |
| `--transform`       | Transform output using [GJSON](https://github.com/tidwall/gjson) syntax               |
| `--transform-error` | Transform error output using GJSON syntax                                             |