CLI configuration

This page covers everything the CLI reads to figure out where to go, who you are, and how to behave: the config file format, the environment variables, the global flags, and how they interact.

Where credentials live

~/.plugipay/config.json for the default profile. ~/.plugipay/config-<name>.json for named profiles.

The file is plain JSON:

{
  "token": "pk_test_AKIAxxxxx:sk_test_xxxxx",
  "api_url": "https://api.plugipay.com",
  "default_account": "acc_01Hxxxxxxxxx",
  "default_mode": "test"
}

Field	What it does
`token`	`"<access_key_id>:<secret>"` — HMAC credentials
`api_url`	Override the base URL (default `https://api.plugipay.com`)
`default_account`	Default workspace ID for commands that need one
`default_mode`	`test` or `live` (informational; the actual mode comes from the key prefix)

The file is created and managed by plugipay auth login — you usually don't edit it by hand.

File permissions matter. The CLI creates this file with mode 0600 (read/write for you, nothing for others). If you copy or back up the file, preserve the permissions — otherwise anyone with shell access to your machine can grab the credentials.

Environment variables

You can override any config file value with environment variables. Precedence is flag > env > config file > built-in default.

Variable	Equivalent
`PLUGIPAY_API_KEY`	`token` — format `<id>:<secret>`
`PLUGIPAY_BASE_URL`	`api_url`
`PLUGIPAY_ACCOUNT_ID`	`default_account`
`PLUGIPAY_MODE`	`default_mode`
`PLUGIPAY_PROFILE`	the profile to use (default `default`)

A typical CI setup:

export PLUGIPAY_API_KEY="${PLUGIPAY_API_KEY_SECRET}"  # from your CI's secret store
plugipay customers list --json | jq '.data[] | .id'

The CLI doesn't read ~/.plugipay/config.json if PLUGIPAY_API_KEY is set — the env wins. This is how you avoid storing credentials on shared CI runners.

Global flags

These flags work on every command:

Flag	What it does
`--json`	Output JSON instead of the default human-readable format
`-q`, `--quiet`	Suppress non-error output
`-v`, `--verbose`	Print request/response details to stderr (useful for debugging)
`--api-key <key>`	Inline auth: `<access_key_id>:<secret>`
`--api <url>`	Override the API base URL
`--profile <name>`	Use a named profile
`--mode <mode>`	`live` or `test` — informational; key prefix is authoritative
`--account <id>`	Override the active workspace ID
`--idempotency-key <key>`	Set the `Idempotency-Key` header on mutating requests
`--no-color`	Disable ANSI colors in output

Example:

plugipay --json --verbose --profile work customers list

Goes to stderr (because of --verbose):

> GET https://api.plugipay.com/v1/customers
> X-Plugipay-Key-Id: pk_test_AKIAxxxxx
> X-Plugipay-Timestamp: 1715526783
> X-Plugipay-Signature: 7c4f...
< 200 OK
< Content-Type: application/json
< X-Request-Id: req_01Hxxxxx

Goes to stdout:

{"data": [...], "meta": {...}}

Output formats

By default, the CLI prints a human-readable table:

plugipay customers list --limit 3

ID                       EMAIL                NAME           CREATED
cus_01HXX...            alice@example.com    Alice Tan      2 hours ago
cus_01HYY...            bob@example.com      Bob Setiawan   3 days ago
cus_01HZZ...            carol@example.com    Carol Wong     1 week ago

With --json:

{
  "data": [
    {"id": "cus_01HXX...", "email": "alice@example.com", "name": "Alice Tan", "createdAt": "..."},
    ...
  ],
  "meta": {"page": {"limit": 3, "hasMore": true, "nextCursor": "cur_xxx"}}
}

Pipe into jq for filtering:

plugipay customers list --json | jq '.data[] | select(.email | contains("@example.com")) | .id'

Some commands also support --output csv for spreadsheet export:

plugipay payments list --since 30d --output csv > payments.csv

Idempotency

Mutating commands accept --idempotency-key:

plugipay refunds create --payment-id pay_01HXX --reason duplicate --idempotency-key my-script-run-001

If the script runs twice, Plugipay returns the same refund both times. The key is workspace-scoped and persists for 24 hours.

When you omit the flag, the CLI auto-generates a key per invocation (a random UUID). This means retries by the user (re-running the command) create new operations, not deduplicated ones. For scripts that should be safely re-runnable, always pass an explicit --idempotency-key that you can derive from your input.

See API → Idempotency for the underlying semantics.

Verbose mode

-v prints the full HTTP request and response (minus the secret signature) to stderr:

plugipay -v customers get cus_01HXXX

> GET https://api.plugipay.com/v1/customers/cus_01HXXX
> Authorization: HMAC-SHA256 pk_test_AKIAxxxxx:[signature redacted]
> X-Plugipay-Timestamp: 1715526783
< 200 OK
< X-Request-Id: req_01Hxx
< X-RateLimit-Remaining: 99
< [body]
{"data": {...}, "meta": {...}}

Use this when debugging unexpected behavior. Include the X-Request-Id if you file a support ticket — we can look up exactly what happened in our logs.

Profiles

A profile is a separate config file. The default profile lives at ~/.plugipay/config.json; named profiles live at ~/.plugipay/config-<name>.json.

Create one:

plugipay auth login --profile work

Use it:

plugipay --profile work customers list

Or via env:

export PLUGIPAY_PROFILE=work
plugipay customers list

Common patterns:

Test vs live — profile test with a test key, profile live with a live key.
Personal vs work — profile personal for your own workspace, profile work for your employer's.
Per-environment — profile staging pointing at api-staging.plugipay.com, profile prod pointing at api.plugipay.com.

Where the CLI writes

Path	When
`~/.plugipay/config.json`	`plugipay auth login` (default profile)
`~/.plugipay/config-<name>.json`	`plugipay auth login --profile <name>`
stderr	`--verbose` output, error messages
stdout	Command output (JSON or formatted)

The CLI never writes elsewhere — no caches, no telemetry, no logs to disk.

Disable color

plugipay --no-color customers list

Or set:

export NO_COLOR=1
plugipay customers list

(Respects the NO_COLOR convention.)

Command reference — the catalog of commands.
Scripting & automation — CI patterns, bulk operations, jq integration.