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

# Subotiz CLI

`subotiz-cli` is a command-line client for Subotiz APIs. It is designed for developers, operators, and automation agents that need to call Subotiz APIs from local machines or CI environments.

It includes configuration management, environment switching, raw API calls, request previews, and output formatting. Command output follows an automation-friendly contract: machine-readable results are written to stdout, while diagnostics, warnings, and errors are written to stderr.

## Install With One Command

For first-time setup, run:

```bash theme={null}
npx @subotiz/cli@latest install
```

This command runs the guided installation and basic setup flow:

* Syncs the packaged Subotiz skills.
* Initializes the local configuration file.
* Optionally prompts for an API key.
* Prints the masked configuration so you can confirm the active environment and config path.

After installation, verify the CLI version:

```bash theme={null}
subotiz-cli version
```

The npm package supports macOS and Linux on `x64` and `arm64`. It ships with prebuilt binaries, so installation does not require Go private module configuration or extra release asset downloads.

## Use Cases

* Quickly debug Subotiz API requests and preview outgoing calls.
* Call payment, subscription, product, price, and other APIs from CI, scripts, or agent environments.
* Manage multiple environments such as `sandbox` and `prod`.
* Use `--dry-run` to preview requests before sending them.
* Process API responses as JSON, NDJSON, CSV, or with `jq` expressions.

<Frame>
  <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/c45c924a-7b24e1b97da668f14a9bb2b4c0b7a8124eb11fafad799f6968b75211-e78cdf42-f247-4f19-b53a-d9c762f1b1bc.png?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=69738603ef88b0ad131a60eeb9675b3d" width="1158" height="1770" data-path="images/c45c924a-7b24e1b97da668f14a9bb2b4c0b7a8124eb11fafad799f6968b75211-e78cdf42-f247-4f19-b53a-d9c762f1b1bc.png" />
</Frame>

## Using With Agents

Skills for coding agents such as Cursor and Claude Code are supported by default. If your agent uses a custom skills directory, copy the relevant skills from `~/.agents/skills/` into that directory.

<Frame>
  <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/18e556ce-b76464b0e7232c165e9c10d7a2d641efa840de9565cd6a14a2836afc-69b3cc3a-eec6-44d1-9f04-d0d756bb5053.png?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=2a5609f8ea4facfee6c4b7385446df81" width="1064" height="2474" data-path="images/18e556ce-b76464b0e7232c165e9c10d7a2d641efa840de9565cd6a14a2836afc-69b3cc3a-eec6-44d1-9f04-d0d756bb5053.png" />
</Frame>

## Key Commands

### Check Version

```bash theme={null}
subotiz-cli version
```

### Show Current Config

```bash theme={null}
subotiz-cli config show
```

`config show` masks sensitive fields such as API keys.

### List Environments

```bash theme={null}
subotiz-cli env list
```

### Switch Default Environment

```bash theme={null}
subotiz-cli env use sandbox
```

### Add Or Update An Environment

```bash theme={null}
subotiz-cli env add sandbox \
  --base-url https://api.sandbox.subotiz.com \
  --api-key "$SUBOTIZ_API_KEY"
```

### Preview An API Request

Use `--dry-run` to print a masked request preview without sending the request:

```bash theme={null}
subotiz-cli api GET /api/v1/products \
  --base-url https://api.sandbox.subotiz.com \
  --api-key "$SUBOTIZ_API_KEY" \
  --query '{"limit":20,"status":"active"}' \
  --dry-run
```

### Send A POST Request

```bash theme={null}
subotiz-cli api POST /api/v1/products \
  --base-url https://api.sandbox.subotiz.com \
  --api-key "$SUBOTIZ_API_KEY" \
  --data '{"name":"demo-product","active":true}' \
  --dry-run
```

Remove `--dry-run` only after confirming the request is correct.

### Read Request Body From A File

`--data` accepts inline JSON or `@file`:

```bash theme={null}
subotiz-cli api PATCH /api/v1/products/prod_demo \
  --base-url https://api.sandbox.subotiz.com \
  --api-key "$SUBOTIZ_API_KEY" \
  --data @payload.json \
  --dry-run
```

## Environment Variables

In CI, scripts, or agent environments, prefer environment variables for runtime configuration:

```bash theme={null}
SUBOTIZ_BASE_URL=https://api.sandbox.subotiz.com \
SUBOTIZ_API_KEY="replace-with-your-own-key" \
SUBOTIZ_ENV=sandbox \
subotiz-cli api GET /api/v1/products --dry-run
```

| Variable           | Description                                          |
| ------------------ | ---------------------------------------------------- |
| `SUBOTIZ_API_KEY`  | API key used when `--api-key` is not provided.       |
| `SUBOTIZ_ENV`      | Environment name used when `--env` is not provided.  |
| `SUBOTIZ_BASE_URL` | API base URL used when `--base-url` is not provided. |

`SUBOTIZ_ENV` mainly affects environment resolution for API requests. It does not change how `env list`, `env use`, `env add`, or `env remove` display or modify the config file.

## Common Global Flags

| Flag                           | Description                                                                               |
| ------------------------------ | ----------------------------------------------------------------------------------------- |
| `--env <name>`                 | Sets the environment name and overrides `SUBOTIZ_ENV` and the default config environment. |
| `--api-key <key>`              | Sets the API key and overrides `SUBOTIZ_API_KEY` and the configured key.                  |
| `--base-url <url>`             | Sets the API base URL and overrides `SUBOTIZ_BASE_URL` and the configured URL.            |
| `--format <json\|ndjson\|csv>` | Sets the API response output format. The default is `json`.                               |
| `--jq <expr>`                  | Filters JSON output with a jq expression.                                                 |
| `--dry-run`                    | Prints a masked request preview without sending the request.                              |
| `--debug` or `-v`              | Enables debug logs on stderr.                                                             |
| `--timeout <duration>`         | Sets the request timeout, for example `10s` or `1m`.                                      |
| `--config <path>`              | Sets the config file path. If empty, the default config path is used.                     |

## Output Contract

`subotiz-cli` separates machine-readable output from human-readable diagnostics:

* stdout: JSON, NDJSON, CSV, or dry-run JSON previews.
* stderr: errors, warnings, debug logs, request IDs, trace IDs, and troubleshooting hints.

Automation scripts should parse stdout only. stderr is intended for diagnostics and should not be treated as a stable API contract.

## Security Recommendations

* Do not paste real API keys into documentation, issues, prompts, shell history, or shared logs.
* Prefer `SUBOTIZ_API_KEY`, CI secrets, or config placeholders for secret management.
* Preview production write requests with `--dry-run` before sending them.
* Write requests with `POST`, `PUT`, `PATCH`, or `DELETE` against `prod` or `https://api.subotiz.com` print a production-write warning to stderr.
* `config show`, dry-run output, debug output, and error output mask sensitive values such as API keys, bearer tokens, secrets, passwords, cookies, and sessions.