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

brew install arcaresearch/tap/arca

Build from Source

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, optional portal URL for browser auth, default realm, and optional API key.

{
  "active_profile": "staging",
  "profiles": {
    "local": {
      "api_base": "http://localhost:3052/api/v1",
      "realm": "development",
      "api_key": "arca_78ae7276_..."
    },
    "staging": {
      "api_base": "https://api-staging.arcaos.io/api/v1",
      "portal_base": "https://app-staging.arcaos.io",
      "realm": "qa-regression"
    }
  }
}

Managing Profiles

# 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_...

# Staging profile (browser auth opens app-staging)
arca config set staging \
  --api-base https://api-staging.arcaos.io/api/v1 \
  --portal-base https://app-staging.arcaos.io
arca config use staging

# 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:

Resolution Priority

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

1. Command-line flags (--api-key, --realm, --org, --profile)
2. Environment variables (ARCA_API_KEY, ARCA_REALM, ARCA_ORG, ARCA_API_BASE, ARCA_PORTAL_BASE)
3. Active profile in ~/.arca/config.json
4. Defaults (API base: http://localhost:3052/api/v1; portal inferred for local, staging, and production API hosts)

Global Flags

Available on every command:

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

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.

arca auth

login

Sign in to an existing account. Opens your browser for authentication. A staging profile opens app-staging.arcaos.io whenportal_base is set, or when the API base is the known staging host.

arca auth login

signup

Create a new builder account. Opens your browser for account creation.

arca auth signup

logout

Clear the saved JWT token and revoke the refresh token.

arca auth logout

whoami

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

arca auth whoami

status

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

arca auth status

token

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

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

CLI: Realm Commands

Manage realms. Aliases: arca realms.

list

arca realm list
arca realm list --output json

create

# Two-axis model (preferred):
arca realm create --name "Trading App" --asset live --lifecycle permanent
arca realm create --name "Bench" --asset paper --lifecycle temporary

# Legacy single-axis type still works:
arca realm create --name "Sandbox" --type development

A realm has two independent axes. Asset is the real-money risk tier: paper realms transact simulated funds (auto-minted, dev chain) while live realms transact real money (KYB-gated, production chain, withdrawals require a real destination, value-moving actions require browser step-up). Lifecycle is the durability tier: permanent realms are never auto-reaped and need step-up to archive; temporary realms are disposable (reaped after 30 days). The two axes are orthogonal — a paper+permanent realm is a long-lived practice app; a live+temporary realm is a short-lived real-money run.

get

arca realm get <realm-id>

delete

arca realm delete <realm-id>
arca realm delete <realm-id> --force   # skip confirmation
arca realm delete <realm-id> --force-production-archive   # required for permanent realms

# Paper realms only (e.g. load-test scaffolding):
arca realm delete <realm-id> --force-pool-imbalance --imbalance-reason "<rationale>"
arca realm delete <realm-id> --force-active-operations --imbalance-reason "<rationale>"

Soft-archives the realm. The preconditions split along the two realm axes. Lifecycle: a permanent realm additionally requires --force-production-archive AND server-side step-up auth (the CLI opens your browser to confirm), because an app depends on its continued existence; a temporary realm needs neither. Asset: a live realm must have zero pool obligations, zero on-chain pool balance, and no pending operations or held reservations before it can be archived.

For paper realms — load-test scaffolding, throwaway probes, integration spins where no human or downstream system depends on the realm — the operator can opt out of the pool-solvency and active-operations preconditions with --force-pool-imbalance and --force-active-operations. Both REQUIRE --imbalance-reason for the audit trail and both are REFUSED on live realms regardless of step-up — see .cursor/rules/ledger-integrity.mdc rule 5 for the policy: a paper realm holds only simulated funds, but a real-purpose one still warrants investigation over archive-and-recreate.

CLI: Object Commands

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

ensure

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

list

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

get

Get an object by its path.

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

detail

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

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.

arca object balances <object-id>
arca object balances <object-id> --output 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).

# 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

labels get

View current labels on an Arca object.

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.

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

labels remove

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

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.

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

fund-account

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

arca fund-account --ref /wallets/main --amount 1000

CLI: Operation Commands

Inspect operations. Aliases: arca operations, arca op.

list

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

get

Get operation detail with correlated events and state deltas.

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.

# 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

CLI: Exchange Commands

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

state

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

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.

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

isolated-margin

Add or remove collateral from an isolated-margin position. A positive --amount (USD) adds collateral and lowers the liquidation price; a negative amount removes it (rejected if it would breach maintenance margin). Only valid on isolated positions.

# Add $25 of margin to an isolated CL position
arca exchange isolated-margin \
  --object <exchange-object-id> \
  --coin hl:1:CL --amount 25

# Remove $10
arca exchange isolated-margin \
  --object <exchange-object-id> \
  --coin hl:1:CL --amount -10

margin-mode

Switch an asset between cross and isolated margin. Rejected on isolated-only markets and while an open position exists for the asset.

arca exchange margin-mode \
  --object <exchange-object-id> \
  --coin hl:0:BTC --mode isolated

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.

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

# Limit order
arca exchange order place \
  --object <exchange-object-id> \
  --coin hl:0: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:0:BTC --side sell --type limit --price 100000 --size 0.01 \
  --path /op/order/btc-tp-1 \
  --trigger --trigger-px 99000 --tpsl tp

order list

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

order get

Get a specific order with its fills.

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

order cancel

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

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

order modify

Resize a resting order to a new total size. Only sized orders can be resized: resting limit orders and sized TP/SL triggers. Unsized (sizeToMax: true) triggers are rejected — they always close the whole position and have no quantity to amend. The --new-size must exceed the order's already-filled quantity; --path is the idempotency key.

arca exchange order modify <order-id> \
  --object <exchange-object-id> \
  --path /op/modify/btc-1-0.75 \
  --new-size 0.75

position list

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

position close

Close an open position with reduceOnly: true enforced. Looks up the position for --coin, infers the closing side, and submits a reduce-only market order sized to close the full position (or --sizefor a partial close). Automatically threads the position's leverage and the market's marginModes into the order — required on isolated-only markets where Hyperliquid's matching engine refuses closes without explicit leverage + isolated.

# Close the full position
arca exchange position close \
  --object <exchange-object-id> \
  --coin hl:1:CL \
  --path /op/close/cl-1

# Partial close
arca exchange position close \
  --object <exchange-object-id> \
  --coin hl:0:BTC --size 0.005 \
  --path /op/close/btc-partial

position set-tpsl

Attach a stop-loss and/or take-profit to an open position. Looks up the position for --coin, infers the closing side (LONG → SELL, SHORT → BUY), and submits each trigger as a reduce-only unsized market order — so when it fires it closes the entire live position regardless of size, and it is cancelled automatically when the position closes or is liquidated. The position's leverage and the market's marginModes are threaded in automatically, exactly like position close.

At least one of --stop-loss / --take-profit is required (each is a trigger price). When both are set, two triggers are placed on derived sub-paths <path>/sl and <path>/tp. By default an existing unsized trigger of the same type is replaced (cancel-then-place); pass --replace=false to stack. For a sized (fixed-quantity) trigger or a limit trigger, use order place --trigger.

# Stop-loss on a long BTC position (places a reduce-only SELL trigger)
arca exchange position set-tpsl \
  --object <exchange-object-id> \
  --coin hl:0:BTC --stop-loss 54000 \
  --path /op/tpsl/btc-sl

# Both legs at once — derives /op/tpsl/btc/sl and /op/tpsl/btc/tp
arca exchange position set-tpsl \
  --object <exchange-object-id> \
  --coin hl:0:BTC --stop-loss 54000 --take-profit 72000 \
  --path /op/tpsl/btc

Triggers execute as market orders when the mark price crosses the threshold. They surface as WAITING_FOR_TRIGGER / TRIGGERED in order list.

position clear-tpsl

Cancel resting unsized triggers for a coin. With no --tpsl filter it clears both legs; pass --tpsl sl or --tpsl tp to clear just one. Sized triggers and other coins are left untouched.

# Clear both stop-loss and take-profit for BTC
arca exchange position clear-tpsl \
  --object <exchange-object-id> \
  --coin hl:0:BTC \
  --path /op/tpsl/btc-clear

# Clear only the stop-loss leg
arca exchange position clear-tpsl \
  --object <exchange-object-id> \
  --coin hl:0:BTC --tpsl sl \
  --path /op/tpsl/btc-clear-sl

fills

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

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

trade-summary

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

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

funding-history

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

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

market meta

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

arca exchange market meta --output json

market mids

Get current mid prices for all assets.

arca exchange market mids --output json

market tickers

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

arca exchange market tickers --output json

market book

Get the L2 order book for a specific coin.

arca exchange market book hl:0: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.

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

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.

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

list

List payment links in the current realm.

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

preview

Show the public preview of a payment link, including the on-chain deposit instructions (pool address, boundary, ref, raw amount) that the pay page would surface to the depositor's browser wallet. Lets test scripts, CI, and any on-chain tool (cast, foundry, Safe, manual MetaMask) drive a deposit without opening the browser. The endpoint is unauthenticated — the token in the URL is the credential — so this works from any machine without first running arca auth login.

arca payment-link preview <token>
arca payment-link preview <token> --output json

complete

Register a payment link's deposit/withdrawal intent on the platform side — the same call the pay page makes after the user clicks Confirm in their browser wallet. For deposit links, this writes the DepositIntentrow the chain monitor matches against; for withdrawal links it kicks off the on-chain operator-withdraw workflow. Pair with preview to drive the full flow from CI or a non-browser tool. Idempotent — a second call on an already-completed link is a no-op.

arca payment-link complete <token>
arca payment-link complete <token> --output json

CLI: Summary

Show aggregate counts for the current realm.

arca summary
arca summary --output json

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