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.

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:8080/api/v1",
      "realm": "development",
      "api_key": "arca_78ae7276_..."
    }
  }
}

Managing Profiles

bash

# Create or update a profile
arca config set local --api-base http://localhost:8080/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_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, --profile)
Environment variables (ARCA_API_KEY, ARCA_REALM, ARCA_API_BASE)
Active profile in ~/.arca/config.json
Defaults (API base: http://localhost:8080/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.

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.

signup

Create a new builder account. Prompts for organization name, email, and password.

bash

arca auth signup

login

Authenticate an existing builder. Prompts for email and password. Saves the JWT to ~/.arca/token.

bash

arca auth login

logout

Clear the saved JWT token.

bash

arca auth logout

whoami

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

bash

arca auth whoami

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.

create

bash

arca object create --path /wallets/main --denomination USD
arca object create --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.

bash

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

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.

CLI: Transfer & Deposit

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.

deposit

Initiate a deposit to a denominated Arca object. In demo realms, deposits are simulated with a configurable delay.

bash

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

--refstringrequired

Target Arca object path.

--amountstringrequired

Deposit amount as a decimal string.

--durationnumber

Simulated processing time in seconds. Default: 5.

--failboolean

Simulate a failed deposit.

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. Returns a path that can be used as the idempotency key for an operation or object creation.

bash

# Operation nonce (colon separator)
arca nonce --prefix /op/create/wallets/main --separator ":"
# → /op/create/wallets/main:1

# Transfer nonce (default hyphen separator)
arca nonce --prefix /op/transfer/fund
# → /op/transfer/fund-1

# Object name nonce
arca nonce --prefix /orders/order
# → /orders/order-47

# JSON output for scripting
arca nonce --prefix /op/transfer/fund --output json
# → { "nonce": 1, "path": "/op/transfer/fund-1" }

--prefixstringrequired

Path prefix for the nonce (e.g., /op/transfer/fund).

--separatorstring

Separator between prefix and nonce number. Default: / if prefix ends with /, otherwise -. Use ":" for operation nonces.

Reserve before you operate

Always reserve the nonce before the operation and store the resulting path. On retry, reuse the stored path. Calling arca nonce inline (e.g., inside a retry loop or as a subshell) produces a new path on every call, turning each retry into a distinct operation and defeating idempotency.

bash

# GOOD — reserve once, store, reuse on retry
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

# BAD — inline nonce defeats idempotency (new path on every call)
arca transfer --path "$(arca nonce --prefix /op/transfer/fund)" --from ... --to ... --amount 250

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

bash

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

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

--objectstringrequired

Exchange Arca object ID.

--coinstringrequired

Coin to trade (e.g., BTC, 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.

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: OPEN, FILLED, CANCELLED, FAILED.

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

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 book

Get the L2 order book for a specific coin.

bash

arca exchange market book BTC --output json

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.

View Organization

bash

arca org info --output json

List Members

bash

arca org members --output table

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

Platform admin commands for internal Arca team use. Requires the is_platform_admin flag on your account.

Dashboard

bash

arca admin dashboard --output json

List Organizations

bash

arca admin orgs --output table

List Users

bash

arca admin users --output table

List All Realms

bash

arca admin realms --output table