Cleared CLI

Run your billing from the terminal. The native cleared CLI brings customers, invoices, payment checks, and your dashboard to your shell, scripts, and agents—with browser sign-in and structured JSON for automation.

Built in Rust, it runs as a single executable on macOS and Linux, on both ARM64 and x86-64. No Node.js, Bun, Cargo, or MCP host is needed to use it. Signing and billing policy stay in the Cleared API; the CLI does not embed a wallet or private key.

Install and get started#

Download the versioned v0.2.2 installer, inspect it, then run it:

curl -fL https://github.com/tinkrtailor/cleared-cli/releases/download/v0.2.2/install.sh -o install.sh
less install.sh
sh install.sh --version 0.2.2
export PATH="$HOME/.local/bin:$PATH"
cleared --version
cleared login
cleared dashboard

The installer selects your platform, verifies the archive against the release's SHA256SUMS, and installs to ~/.local/bin. It requires curl, standard shell/archive tools, and sha256sum or shasum. It uses no sudo and does not edit your shell startup files; add the PATH setting there if you want it in future shells. Use --install-dir DIR for another destination.

For manual downloads, checksums, and release notes, see v0.2.2. macOS binaries are currently unsigned and unnotarized, so macOS may require approval in Privacy & Security. Binaries are distributed under proprietary use terms; source code remains private.

Explore your billing#

Start with read-only commands:

cleared customers list --limit 20
cleared invoices list --status issued --limit 20
cleared --json dashboard
cleared protocol info --chain base

In the examples below, replace CUSTOMER_UUID, INVOICE_ID, and cursor placeholders with values returned for your own account. Invoice commands accept a global invoice ID or a formatted number such as INV-YYYY-NNNNNN; use the exact value returned by Cleared. For automation, prefer customer UUIDs over names or email addresses.

cleared customers get 'CUSTOMER_UUID'
cleared invoices get 'INVOICE_ID'
cleared invoices pay-link 'INVOICE_ID'
cleared payments check --invoice 'INVOICE_ID'
cleared payments check --customer 'CUSTOMER_UUID' --limit 20

Payment links retain their access token. Share the complete returned link with the intended customer; do not strip its query string or put tokenized links in logs. The CLI checks payments; customers pay through the pay page.

Follow each page#

Lists return one page, not the full account history. Inspect the returned pagination and coverage metadata, then pass the next cursor with the same filters:

cleared --json invoices list --status issued --limit 20 --cursor 'RETURNED_INVOICE_CURSOR'
cleared --json payments check --customer 'CUSTOMER_UUID' --limit 20 --cursor 'RETURNED_PAYMENT_CURSOR'
cleared --json customers list --limit 20 --cursor 'RETURNED_CUSTOMER_OFFSET'

Invoice and customer-payment cursors are opaque: preserve them exactly. Customer-list cursors are offsets. Stop when there is no next page (next_cursor is null). A customer payment page is not full payment history, and partial or degraded results should not be treated as complete totals.

Sign in interactively#

cleared login
cleared auth status

The CLI opens Cleared's existing Privy sign-in and an explicit consent screen. Default access is read-only: invoice:read, customer:read, and dashboard:read. The screen shows the selected organization, exact API origin, and requested scopes. The flow uses an authorization code, S256 PKCE, and an exact 127.0.0.1 callback; the public CLI has no client secret and does not receive an API key or Privy token.

Login stores the opaque Cleared access and refresh tokens only in macOS Keychain or Linux Secret Service. Linux login needs an available, unlocked Secret Service on your user's D-Bus session. If that secure store is locked or unavailable, login fails without writing a plaintext fallback. Credentials are bound to the exact API and web origins, organization, user, client, audience, and approved scopes.

Use a custom scope set only when needed:

cleared login --scope invoice:read,customer:read,dashboard:read
cleared login --scope invoice:read,invoice:write,customer:read,customer:write,dashboard:read

Write scopes imply the corresponding read scope. Consent does not activate a signing session. Invoice issue/cancel still requires the organization's active, chain-correct server signing session from web Settings; otherwise the CLI returns NO_ACTIVE_SIGNER. Browser login never grants withdrawal or arbitrary Safe authority.

Issue, update, and cancel#

Before writing, request the scopes above for the operations you need. Issuance also requires a completed business profile, an existing customer, and an active signing session in web Settings.

The following commands change your account. Replace every uppercase placeholder and choose your actual amount and description before running them. Generate and retain a fresh unique idempotency key for each new invoice operation.

cleared invoices send \
  --customer 'CUSTOMER_UUID' \
  --amount 500.00 \
  --description 'YOUR_INVOICE_DESCRIPTION' \
  --idempotency-key 'YOUR_RETAINED_UNIQUE_OPERATION_KEY' \
  --due-days 30

Amounts are USDC decimals with up to six fractional digits. Due days range from 1 to 3650. Add --send-email to email the payment link. For file-based workflows, cleared invoices send --input invoice.json accepts the documented JSON fields; do not combine --input with business flags.

Customer creation and updates are available through cleared customers create and cleared customers update ID, with billing flags or --input FILE. Creation requires name, email, a full address, and a registration number for an entity. Updates cannot change customer type; replacing an address requires all four address fields. See the public README and each command's --help for input details.

Cancel an unpaid invoice with:

cleared invoices cancel 'INVOICE_ID'

Only Issued invoices can become Canceled; Paid is terminal. An invoice already proven Canceled is a completed no-op.

Retain recovery information#

Save the issuance idempotency key before sending, and retain the returned meta.recovery.input. After a pending or uncertain issuance, use the same key and exact recovery input. Never create a new key just because a response was lost. IDEMPOTENCY_SUBMISSION_UNCERTAIN requires reconciliation or support, not repeated submissions. If issuance succeeds but payment-link retrieval fails, retrieve the link rather than issuing again.

Cancellation submits once with a server-owned operation identity. After a pending or uncertain cancellation, run cleared invoices get INVOICE_ID to reconcile instead of automatically canceling again. A read of Issued does not prove an in-flight cancellation failed. The CLI does not automatically retry mutations or wait for completion.

JSON and exit statuses#

Add --json before or after any subcommand to emit one JSON object per completed invocation, including errors. --help and --version remain informational text. IDs are strings; USDC values preserve exact atomic and decimal representations, for example {"atomic":"1000001","decimal":"1.000001"}.

cleared --json invoices list --status paid --limit 20
cleared --json payments check --invoice 'INVOICE_ID'

Inspect both the exit status and result metadata in scripts:

Exit 0 for a list means that page completed, not that every page was fetched. Exit 8 can contain useful data alongside incomplete coverage or a failed follow-up request; inspect it before using it for reporting.

Headless use#

cleared login --no-browser prints a copyable authorization URL and waits on the same protected loopback callback. Open that URL in a browser on the same machine. If your remote host cannot receive that callback, configure CLEARED_KEY_ID and CLEARED_API_KEY through your secret manager instead. Cleared does not substitute a custom device flow.

Create a scoped API key in web Settings for CI, unattended scripts, or agents, then inject both variables into the process environment. Invoice writes still require an active signing session. The CLI neither creates keys nor activates sessions, accepts no secret command-line flags, and does not load .env files.

Session lifecycle#

Access tokens last at most 15 minutes. Refresh tokens rotate on every use within a session lasting at most 30 days. The CLI serializes refresh across local processes, adopts a replacement produced by another process, and fails closed on an ambiguous refresh response. Safe reads can refresh and retry once after a 401; mutations are not replayed after an ambiguous dispatch.

cleared auth status reads redacted local metadata. Add --validate to contact Cleared and report a revoked or expired grant. cleared logout attempts remote revocation and local credential removal even when remote confirmation fails; check its result for failures. It never changes API-key environment variables.

Origins and precedence#

Production defaults are https://api.clearedpay.xyz and https://clearedpay.xyz. Custom deployments must set matching --api-url and --web-url values (or CLEARED_API_URL and CLEARED_WEB_URL) before login and on later commands. A credential is never reused for another origin pair.

For a custom API that returns relative payment links, explicitly set its matching --pay-url or CLEARED_PAY_URL too. Remote API origins require HTTPS.

A complete CLEARED_KEY_ID plus CLEARED_API_KEY pair always wins for authenticated commands. A partial pair is an error and never falls back to OAuth. Public protocol queries send neither credential.

Keep OAuth tokens, authorization URLs, callback queries, API keys, and full tokenized invoice links out of logs and support reports.

Reference and downloads#

• Public CLI README: complete usage, configuration, and binary terms.
• Releases: native downloads, checksums, and version notes.
• cleared --help or cleared COMMAND --help: installed-version command reference.