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:

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:

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.

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.

Key Commands

Check Version

subotiz-cli version

Show Current Config

subotiz-cli config show

config show masks sensitive fields such as API keys.

List Environments

subotiz-cli env list

Switch Default Environment

subotiz-cli env use sandbox

Add Or Update An Environment

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:

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

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:

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:

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.