Documentation

CLI: Installation & Configuration

The Arca CLI is a Go binary built with the Cobra framework. It communicates with the Arca API and supports multiple named profiles.

Install via Homebrew

bash

brew install arcaresearch/tap/arca

Build from Source

bash

cd cli && go build -o arca .
# Optionally add cli/ to your PATH

Configuration File

Configuration is stored at ~/.arca/config.json. Each profile contains an API base URL, default realm, and optional API key.

json

{
  "active_profile": "local",
  "profiles": {
    "local": {
      "api_base": "http://localhost:3052/api/v1",
      "realm": "development",
      "api_key": "arca_78ae7276_..."
    }
  }
}

Managing Profiles

bash

# Create or update a profile
arca config set local --api-base http://localhost:3052/api/v1
arca config set local --realm development
arca config set local --api-key arca_78ae7276_...

# Switch the active profile
arca config use local

# List all profiles
arca config list

# View a specific profile
arca config get local

Environment Variables

Environment variables override profile settings:

ARCA_API_BASEstring

API base URL. Overrides the profile api_base value.

ARCA_REALMstring

Default realm slug or ID. Overrides the profile realm value.

ARCA_API_KEYstring

API key for authentication. Overrides profile api_key and any saved JWT.

ARCA_ORGstring

Active organization ID or slug for org-scoped commands.

ARCA_CONFIG_DIRstring

Override the config directory. Default: ~/.arca.

Resolution Priority

For each setting, the CLI resolves values in this order (highest priority first):

Command-line flags (--api-key, --realm, --org, --profile)
Environment variables (ARCA_API_KEY, ARCA_REALM, ARCA_ORG, ARCA_API_BASE)
Active profile in ~/.arca/config.json
Defaults (API base: http://localhost:3052/api/v1)

Global Flags

Available on every command:

--realmstring

Realm slug or ID. Overrides the profile and environment variable.

--api-keystring

API key for authentication. Overrides JWT token.

--outputstring

Output format: text (default), json, or table.

--no-colorboolean

Disable colored terminal output.

--profilestring

Named profile from ~/.arca/config.json.

--orgstring

Organization ID or slug for context. Overrides ARCA_ORG environment variable.

Use ARCA_ORG to set the active organization for scripting and CI. It overrides the profile's org value.

Tip

Always use --output json when scripting or verifying behavior programmatically. Text output is for humans; JSON is for automation.

CLI: Auth Commands

Manage builder authentication. JWT tokens are stored at ~/.arca/token after login/signup.

Quick Start

Running arca auth without a subcommand launches an interactive setup wizard that walks you through login (or account creation), API key setup, and realm selection.

bash

arca auth

login

Sign in to an existing account. Opens your browser for authentication by default. Use --no-browser for headless environments (SSH, containers, CI).

bash

arca auth login
# Headless / CI:
arca auth login --no-browser

signup

Create a new builder account. Opens your browser by default. Use --no-browser for terminal-based signup.

bash

arca auth signup

logout

Clear the saved JWT token and revoke the refresh token.

bash

arca auth logout

whoami

Show the current authenticated identity (organization name, email, builder ID).

bash

arca auth whoami

status

Show the current authentication state: method (JWT or API key), active profile, API base, and realm.

bash

arca auth status

token

Mint a scoped JWT for end-user access. Returns a short-lived token with IAM-style policy statements.

bash

arca auth token \
  --sub user123 \
  --actions arca:Read,arca:TransferFrom,arca:ReceiveTo \
  --resources "/users/user123/*" \
  --expiration 30

--substringrequired

Subject identifier (opaque end-user ID).

--actionsstring[]required

Comma-separated actions (e.g., arca:Read,arca:Transfer).

--resourcesstring[]required

Comma-separated resource patterns (e.g., /users/*).

--realm-idstring

Realm ID. Defaults to the current profile realm.

--expirationnumber

Token TTL in minutes (1–1440). Default: 60.

CLI: Realm Commands

Manage realms. Aliases: arca realms.

list

bash

arca realm list
arca realm list --output json

create

bash

arca realm create --name "Production" --type production --description "Live environment"

--namestringrequired

Realm name. A URL-safe slug is generated automatically.

--typestring

Either demo (default) or production.

--descriptionstring

Optional description.

get

bash

arca realm get <realm-id>

delete

bash

arca realm delete <realm-id>
arca realm delete <realm-id> --force   # skip confirmation

--forceboolean

Skip the interactive confirmation prompt.

CLI: Object Commands

Manage Arca objects. Aliases: arca objects, arca obj.

ensure

bash

arca object ensure --path /wallets/main --denomination USD
arca object ensure --path /exchanges/hl1 --type exchange

--pathstringrequired

Hierarchical Arca path (e.g., /wallets/main).

--typestring

Object type: denominated (default), exchange, deposit, withdrawal, escrow.

--denominationstring

Currency or asset denomination (e.g., USD). Default: USD.

--metadatastring

Optional metadata as a JSON string.

--operation-pathstring

Operation path serving as the idempotency key.

list

bash

arca object list
arca object list --prefix /wallets --output json
arca object list --include-deleted

--prefixstring

Filter by path prefix (e.g., /wallets).

--include-deletedboolean

Include deleted and deleting objects in results.

get

Get an object by its path.

bash

arca object get /wallets/main
arca object get /wallets/main --output json

detail

Get full object detail including operations, events, deltas, and balances.

bash

arca object detail <object-id> --output json

balances

Get current balances for an Arca object. Each balance includes arriving, settled, departing, and total fields showing in-flight transfer state.

bash

arca object balances <object-id>
arca object balances <object-id> --output json

json

[
  {
    "denomination": "USD",
    "arriving": "200.00",
    "settled": "800.00",
    "departing": "0.00",
    "total": "1000.00"
  }
]

delete

Delete an Arca object. If the object has non-zero balances, use --sweep-to to transfer remaining funds before deletion. For exchange objects with open positions, use --liquidate to close all positions via market order first. Deletion is blocked if the object has in-flight operations (pending transfers or deposits).

bash

# Simple deletion
arca object delete /wallets/old --force

# Deletion with balance sweep
arca object delete /wallets/old --sweep-to /wallets/main --force

# Exchange deletion with liquidation
arca object delete /exchanges/hl1 --sweep-to /wallets/main --liquidate --force

--sweep-tostring

Arca path to sweep remaining funds into before deletion.

--liquidateboolean

Liquidate all exchange positions via market order before deletion. Required for exchange objects with open positions.

--forceboolean

Skip the interactive confirmation prompt.

labels get

View current labels on an Arca object.

bash

arca object labels get <object-id>
arca object labels get <object-id> --output json

labels set

Set one or more labels on an Arca object. Uses merge semantics — existing labels not mentioned in the command are left unchanged.

bash

arca object labels set <object-id> displayName="Main Wallet" tier=gold
arca object labels set <object-id> stripeCustomerId=cus_abc123

key=valuestringrequired

One or more label key-value pairs. Keys must start with a letter (a-z/A-Z), contain only a-z, A-Z, 0-9, ., _, -, and be 1–63 characters. Values are max 256 characters. Keys prefixed with arca. or _ are reserved.

labels remove

Remove one or more labels from an Arca object by key.

bash

arca object labels remove <object-id> tier supportTicket
arca object labels remove <object-id> displayName

CLI: Transfer & Fund Account

transfer

Execute an atomic transfer between two Arca objects. The --path serves as the idempotency key — resubmitting the same path returns the existing result without a double-spend.

bash

arca transfer \
  --path /op/transfer/alice-to-bob-1 \
  --from /wallets/alice \
  --to /wallets/bob \
  --amount 250

--pathstringrequired

Operation path (idempotency key). Must be unique per realm.

--fromstringrequired

Source Arca object path to debit.

--tostringrequired

Target Arca object path to credit.

--amountstringrequired

Transfer amount as a decimal string.

fund-account

Fund an Arca object (denominated or exchange). This is a developer tool for testing, competitions, and programmatic account seeding. In demo realms, funding is simulated with a configurable delay. For production deposit flows, use payment links.

bash

arca fund-account --ref /wallets/main --amount 1000
arca fund-account --ref /wallets/main --amount 500 --duration 10
arca fund-account --ref /wallets/main --amount 100 --fail

--refstringrequired

Target Arca object path.

--amountstringrequired

Amount as a decimal string.

--durationnumber

Simulated processing time in seconds. Default: 5.

--failboolean

Simulate a failed funding operation.

CLI: Operation Commands

Inspect operations. Aliases: arca operations, arca op.

list

bash

arca operation list --output json
arca operation list --type transfer --output json
arca operation list --type deposit

--typestring

Filter by operation type: transfer, create, delete, deposit, order, cancel.

get

Get operation detail with correlated events and state deltas.

bash

arca operation get <operation-id> --output json

nonce

Reserve the next unique nonce for a path prefix. Always reserve before the operation and store the result — see Nonce Best Practices in the API Reference.

bash

# Reserve a nonce, then use it
NONCE_PATH=$(arca nonce --prefix /op/transfer/fund --output json | jq -r .path)
arca transfer --path "$NONCE_PATH" --from /wallets/alice --to /wallets/bob --amount 250

# Colon separator for create-operation nonces
arca nonce --prefix /op/create/wallets/main --separator ":"
# → /op/create/wallets/main:1

--prefixstringrequired

Path prefix for the nonce.

--separatorstring

Override separator. Default: - (or / if prefix ends with /). Use ":" for operation nonces.

CLI: Exchange Commands

Trade perpetual futures on exchange Arca objects. Aliases: arca ex.

state

Get exchange account state (equity, margin summary, positions, open orders).

bash

arca exchange state <object-id> --output json

leverage set

Set the leverage for a coin. Leverage is a per-coin setting, not per-order. Must be set before placing orders at non-default leverage.

bash

arca exchange leverage set \
  --object <exchange-object-id> \
  --coin hl:BTC --leverage 10

order place

Place a market or limit order. The --path is the idempotency key. Orders use the leverage currently set for the coin. For take-profit / stop-loss triggers, pass --trigger with --trigger-px and --tpsl; use --trigger-market for a market execution when triggered, or omit it to use --price as the limit after trigger.

bash

# Market order
arca exchange order place \
  --object <exchange-object-id> \
  --coin hl:BTC --side buy --size 0.01 \
  --path /op/order/btc-buy-1

# Limit order
arca exchange order place \
  --object <exchange-object-id> \
  --coin hl:ETH --side sell --type limit --price 3000 --size 1 \
  --path /op/order/eth-sell-1

# Trigger order (TP) — limit when triggered
arca exchange order place \
  --object <exchange-object-id> \
  --coin hl:BTC --side sell --type limit --price 100000 --size 0.01 \
  --path /op/order/btc-tp-1 \
  --trigger --trigger-px 99000 --tpsl tp --grouping normalTpsl

--objectstringrequired

Exchange Arca object ID.

--coinstringrequired

Canonical market ID (e.g., hl:BTC, hl:ETH).

--sidestringrequired

Order side: buy or sell.

--sizestringrequired

Order size as a decimal string.

--pathstringrequired

Operation path (idempotency key).

--typestring

Order type: market (default) or limit.

--pricestring

Limit price. Required for limit orders.

--reduce-onlyboolean

Only reduce an existing position.

--tifstring

Time in force: GTC (default), IOC, ALO.

--triggerboolean

Place as a trigger order (TP/SL). When set, --trigger-px and --tpsl are required.

--trigger-pxstring

Mark price threshold to activate the order.

--trigger-marketboolean

Execute as market when triggered (default: limit using --price).

--tpslstring

tp (take profit) or sl (stop loss). Required with --trigger.

--groupingstring

TP/SL grouping: na (default, standalone), normalTpsl (parent-linked OCO), positionTpsl (tracks position).

order list

bash

arca exchange order list --object <id> --output json
arca exchange order list --object <id> --status OPEN

--objectstringrequired

Exchange Arca object ID.

--statusstring

Filter by status: PENDING, OPEN, PARTIALLY_FILLED, FILLED, CANCELLED, FAILED, WAITING_FOR_TRIGGER, TRIGGERED.

order get

Get a specific order with its fills.

bash

arca exchange order get <order-id> --object <id> --output json

order cancel

Cancel an open order. The --path is the idempotency key.

bash

arca exchange order cancel <order-id> \
  --object <exchange-object-id> \
  --path /op/cancel/btc-1

position list

bash

arca exchange position list --object <id> --output json

fills

List historical fills (trades) with per-fill P&L, fee breakdown, and trade direction.

bash

arca exchange fills --object <id> --output json
arca exchange fills --object <id> --market hl:BTC --limit 50
arca exchange fills --object <id> --start-time 2026-01-01T00:00:00.000000Z

--objectstringrequired

Exchange Arca object ID.

--marketstring

Filter by market coin (e.g. hl:BTC).

--start-timestring

RFC 3339 timestamp — fills on or after.

--end-timestring

RFC 3339 timestamp — fills on or before.

--limitnumber

Max fills to return (default 100, max 500).

--cursorstring

Pagination cursor.

trade-summary

Per-market P&L summary: realized P&L, total fees, trade count, and volume.

bash

arca exchange trade-summary --object <id> --output json
arca exchange trade-summary --object <id> --output table

--objectstringrequired

Exchange Arca object ID.

--start-timestring

RFC 3339 timestamp — scope summary start.

--end-timestring

RFC 3339 timestamp — scope summary end.

funding-history

List hourly funding payments applied to an exchange account. Payments are signed — negative means the account paid, positive means it received.

bash

arca exchange funding-history --object <id> --output json
arca exchange funding-history --object <id> --limit 50 --output table

--objectstringrequired

Exchange Arca object ID.

--limitnumber

Max records to return (default 100, max 500).

market meta

Get market metadata (supported assets, max leverage, size decimals).

bash

arca exchange market meta --output json

market mids

Get current mid prices for all assets.

bash

arca exchange market mids --output json

market tickers

Get 24h ticker data for all assets (volume, price change, funding, delisted status).

bash

arca exchange market tickers --output json

market book

Get the L2 order book for a specific coin.

bash

arca exchange market book hl:BTC --output json

CLI: PnL Commands

Compute profit-and-loss over time for a path prefix.

history

Fetch P&L history over a time range.

bash

arca pnl history --from 2026-01-01T00:00:00Z --to 2026-03-10T00:00:00Z
arca pnl history --prefix / --from 2026-01-01T00:00:00Z --to 2026-03-10T00:00:00Z --points 200 --output json

--prefixstring

Path prefix to compute P&L for. Default: /.

--fromstringrequired

Start timestamp (RFC 3339).

--tostringrequired

End timestamp (RFC 3339).

--pointsnumber

Number of data points. Default: 200.

--outputstring

Output format: json or table.

CLI: Payment Link Commands

Create and manage shareable payment links for deposits and withdrawals. Aliases: arca pl.

create

Create a payment link. Returns the shareable URL for the end user.

bash

arca payment-link create \
  --type deposit \
  --ref /wallets/main \
  --amount 100

# With return URL (web redirect)
arca payment-link create \
  --type withdrawal \
  --ref /wallets/main \
  --amount 50 \
  --return-url https://example.com/thanks \
  --expires-in 60

# For native apps using in-app browsers
arca payment-link create \
  --type deposit \
  --ref /wallets/main \
  --amount 100 \
  --return-strategy close

--typestringrequired

Link type: deposit or withdrawal.

--refstringrequired

Target Arca object path.

--amountstringrequired

Amount as a decimal string.

--return-urlstring

URL to redirect or navigate the end user to after completion. Required for redirect and navigate strategies.

--return-strategystring

How the portal navigates back: redirect (default), navigate (custom URL scheme), or close (dismiss web view).

--expires-innumber

Expiration window in minutes. Default: 1440 (24 hours).

list

List payment links in the current realm.

bash

arca payment-link list
arca payment-link list --output json
arca payment-link list --type deposit --status pending

--typestring

Filter by type: deposit or withdrawal.

--statusstring

Filter by status: pending, completed, expired.

CLI: Summary

Show aggregate counts for the current realm.

bash

arca summary
arca summary --output json

Returns object count, operation count, event count, pending operations, and expired operations.

Advanced: API Keys, Permissions, Org, Fees & Admin ▸

CLI: API Key Commands

Manage API keys for programmatic access. Aliases: arca api-keys.

list

bash

arca api-key list
arca api-key list --output json

create

Create a new API key. The raw key is shown once at creation — save it immediately.

bash

arca api-key create --name "ci-pipeline"

--namestringrequired

A descriptive name for the API key.

Important

The full key is only displayed at creation time. Store it securely — it cannot be retrieved later.

revoke

Permanently revoke an API key. This cannot be undone.

bash

arca api-key revoke <key-id>
arca api-key revoke <key-id> --force   # skip confirmation

--forceboolean

Skip the interactive confirmation prompt.

CLI: Permissions

View the Arca action catalog — all available permissions grouped by category, plus convenience aliases.

bash

arca permissions --output json

See the Scoped Tokens & Permissions section for the full catalog and authorization model.

CLI: Org & Team

Manage your organization and team members from the command line. Aliases: arca org, arca organizations.

list

List organizations you belong to.

bash

arca org list
arca org ls
arca org list --output json

create

Create a new organization. You become the owner.

bash

arca org create --name "Acme Inc"

--namestringrequired

Organization name.

switch

Set the active organization in your profile for subsequent commands.

bash

arca org switch acme-inc
arca org use org-uuid
arca org switch <org-id-or-slug>

org-id-or-slugstringrequired

Organization ID (UUID) or slug.

View Organization

bash

arca org info --output json

invitations

List pending invitations to your organization.

bash

arca org invitations
arca org invites
arca org invitations --output json

revoke-invitation

Revoke a pending invitation.

bash

arca org revoke-invitation <invitation-id>
arca org revoke-invitation inv_abc123 --force

invitation-idstringrequired

The invitation ID to revoke.

List Members

bash

arca org members --output table

remove-member

Remove a member from the organization. Cannot remove the owner.

bash

arca org remove-member <member-id>
arca org remove-member member_abc123 --force

member-idstringrequired

The member ID to remove.

Invite a Member

bash

arca org invite --email alice@example.com --role developer

Available roles: admin, developer, viewer. The invitee receives an invitation link. You cannot assign a role higher than your own (privilege escalation protection).

Transfer Ownership

bash

arca org transfer-ownership <user-id>

Transfers organization ownership to another member. Only the current owner can do this.

CLI: Fee Commands

Estimate fees and view the current fee schedule.

estimate

Estimate the fee for a transfer or order before executing it.

bash

arca fees estimate --action transfer --from /wallets/main --to /exchange/main --amount 1000
arca fees estimate --action transfer --amount 500 --output json

--actionstringrequired

Action type: transfer or order.

--amountstringrequired

Amount as a decimal string.

--fromstring

Source Arca path.

--tostring

Target Arca path.

schedule

Display the current fee schedule.

bash

arca fees schedule
arca fees schedule --output table

CLI: Admin Commands (Internal)

The arca admin subcommands provide operator visibility into platform health. These are not published to Homebrew and require admin auth.

After arca admin auth login, print the Authorization header line for use with curl:

bash

arca admin auth print-header

curl -sS "$ARCA_API_BASE/admin/chain-transactions/bulk-abandon" \
  -H "$(arca admin auth print-header | tr -d '\n')" \
  -H "Content-Type: application/json" \
  -d '{"type":"unlinked","minAge":"7d"}'

venue-health

Venue reconciliation diagnostics: fill audit, adjustments, drift state, and unmatched fills. See the venue reconciliation design doc for context.

bash

# Aggregate stats
arca admin venue-health summary --output json

# Fill audit (fee breakdown, cloid match status)
arca admin venue-health fill-audit --realm-id <realmId> --output json

# Venue adjustment log
arca admin venue-health adjustments --realm-id <realmId> --output json

# Per-account reconciliation state
arca admin venue-health reconciliation --realm-id <realmId> --output json
arca admin venue-health reconciliation --output json

# Unmatched fill operations (external trades)
arca admin venue-health unmatched-fills --output json

# Acknowledge an adjustment (operator role)
arca admin venue-health ack <adjustmentId>

--realm-idstring

Filter by realm. Omitted for summary, reconciliation (all), unmatched-fills.

--outputstring

json or table. Use json for scripting.