Brickken CLI

Public x402-paid CLI for the Brickken agentic API.

It covers:

• ERC-8004 agent identity operations
• ERC-8004 reputation feedback operations
• ERC-8226 RAMS mandate lifecycle, compliance, executor, read, and EIP-712 signing operations
• x402-capable agentic token create, mint, burn, transfer, transfer-from, and approve operations
• raw transaction preparation, signing, sending, and one-shot execution

Repository: https://github.com/Brickken/brickken-api-cli

Install

npm install -g brickken-cli

AI Agent Skill

The npm package includes the Brickken Codex skill at skills/brickken.

Install it into the default Codex skills directory:

brickken skill install

Install it into a custom skills directory:

brickken skill install --path ~/.codex/skills --force

Print the bundled skill path:

brickken skill path

Authentication

Transaction writes use x402 and never send an API key. RAMS read and typed-data endpoints require a Brickken API key:

export BRICKKEN_API_KEY=...

Provide a private key for local transaction signing and x402 payment signing:

export BRICKKEN_PRIVATE_KEY=0x...

Quick Start

The high-level commands are wallet-first and prepare-only by default. Add --execute to prepare, sign locally, send, and pay the API request through x402 in one step.

Agentic operations do not require a tokenizer user in the Brickken database. --owner-email is optional metadata and can be omitted.

For a QA-oriented terminal walkthrough, see QA_TERMINAL_DEMO.md.

Example setup:

export BASE_URL="https://api.sandbox.brickken.com"
export CHAIN="11155111"
export WALLET="0xYourWallet"
export BRICKKEN_RPC_URL="https://ethereum-sepolia-rpc.publicnode.com"

The CLI accepts chain identifiers as decimal or hex-like values. For example, Sepolia can be passed as 11155111 or aa36a7.

Sanity checks:

brickken --version
test -n "$BRICKKEN_PRIVATE_KEY" && echo "private key ok" || echo "private key missing"
test -n "$BRICKKEN_RPC_URL" && echo "rpc ok" || echo "rpc missing"
command -v jq

Environment Notes

• Prefer sandbox or another environment with agent persistence enabled for the full register -> set-uri -> set-metadata flow.
• Public explorers such as 8004scan may not index non-public environments even when the on-chain transaction succeeded.
• Budget Sepolia USDC accordingly. A full QA run with retries can consume roughly 0.02 USDC per executed command because both prepare and send are x402-priced.

Input Safety

The CLI supports --json. When a command appears to "drop" fields, the usual cause is shell expansion, empty variables, or inline JSON quoting, not the JSON output flag itself.

• Quote every variable that can contain spaces.
• Prefer --file for nested JSON, long text, automation, or values assembled by shell scripts.
• Echo critical variables such as AGENT_UUID and TOKEN_ADDRESS before reusing them in the next command.
• Do not continue from create-token into mint or burn unless tokenAddress is present in the output.

Agent Flow

Register the agent:

brickken agent register \
  --chain "$CHAIN" \
  --signer-address "$WALLET" \
  --name "Research Agent" \
  --description "On-chain AI research agent" \
  --image https://example.com/agent.png \
  --service-name A2A \
  --service-endpoint https://agent.example/.well-known/agent-card.json \
  --service-version 0.3.0 \
  --ai-model-provider OpenAI \
  --ai-model-name "Research Model" \
  --x402-support true \
  --execute \
  --json | tee register-output.json

Capture the returned UUID:

export AGENT_UUID="$(jq -r '.prepared.info.agentUuid' register-output.json)"

Finalize the agent profile:

brickken agent set-uri \
  --chain "$CHAIN" \
  --signer-address "$WALLET" \
  --agent-uuid "$AGENT_UUID" \
  --name "Research Agent" \
  --description "On-chain AI research agent" \
  --image https://example.com/agent.png \
  --service-name A2A \
  --service-endpoint https://agent.example/.well-known/agent-card.json \
  --service-version 0.3.0 \
  --ai-model-provider OpenAI \
  --ai-model-name "Research Model" \
  --tag ai-agent \
  --tag terminal-demo \
  --documentation https://docs.brickken.com \
  --source-code https://github.com/Brickken/brickken-api-cli \
  --license MIT \
  --agent-type research \
  --supported-trust feedback \
  --x402-support true \
  --active true \
  --execute \
  --json

Set structured agent metadata:

brickken agent set-metadata \
  --chain "$CHAIN" \
  --signer-address "$WALLET" \
  --agent-uuid "$AGENT_UUID" \
  --metadata-key capabilities \
  --metadata-value '{"tasks":["research","summarization","token-operations"]}' \
  --metadata-encoding json \
  --execute \
  --json

For more complex metadata payloads, prefer a file:

cat > metadata.json <<'EOF'
{
  "chain": "11155111",
  "signerAddress": "0xYourWallet",
  "agentUuid": "00000000-0000-0000-0000-000000000000",
  "metadataKey": "capabilities",
  "metadataValue": "{\"tasks\":[\"research\",\"summarization\",\"token-operations\"]}",
  "metadataEncoding": "json"
}
EOF

brickken tx prepare \
  --method agentSetMetadata \
  --file metadata.json \
  --execute \
  --json

Token Flow

Deploy an agentic token through the high-level command:

brickken create-token \
  --chain "$CHAIN" \
  --signer-address "$WALLET" \
  --name "Research Agent Token" \
  --symbol RAGT \
  --agent-wallet "$WALLET" \
  --premint 1000 \
  --decimals 18 \
  --execute \
  --json | tee create-token-output.json

When create-token --execute succeeds, the CLI waits for the deployment receipt and adds tokenAddress to the JSON output. Sepolia has a built-in public RPC fallback; for other chains set --rpc-url, BRICKKEN_RPC_URL, or BKN_RPC_URL.

export TOKEN_ADDRESS="$(jq -r '.tokenAddress' create-token-output.json)"

Mint more tokens:

brickken mint \
  --chain "$CHAIN" \
  --signer-address "$WALLET" \
  --token-address 0xDeployedAgentToken \
  --to 0xRecipientWallet \
  --amount 100 \
  --decimals 18 \
  --execute \
  --json

Burn tokens:

brickken burn \
  --chain "$CHAIN" \
  --signer-address "$WALLET" \
  --token-address 0xDeployedAgentToken \
  --from 0xHolderWallet \
  --amount 25 \
  --decimals 18 \
  --execute \
  --json

Approve allowance:

brickken approve \
  --chain "$CHAIN" \
  --signer-address "$WALLET" \
  --token-address 0xDeployedAgentToken \
  --spender-address 0xSpenderWallet \
  --amount 50 \
  --decimals 18 \
  --execute \
  --json

Transfer tokens:

brickken transfer \
  --chain "$CHAIN" \
  --signer-address "$WALLET" \
  --token-address 0xDeployedAgentToken \
  --to 0xRecipientWallet \
  --amount 10 \
  --decimals 18 \
  --execute \
  --json

Transfer through allowance:

brickken transfer-from \
  --chain "$CHAIN" \
  --signer-address 0xApprovedSpenderWallet \
  --token-address 0xDeployedAgentToken \
  --from 0xTokenHolderWallet \
  --to 0xRecipientWallet \
  --amount 5 \
  --decimals 18 \
  --execute \
  --json

The high-level create-token, mint, burn, transfer, transfer-from, and approve commands use the agentic backend methods agentCreateToken, agentMintToken, agentBurnToken, agentTransferToken, agentTransferFromToken, and agentApproveToken.

Command Groups

• brickken agent: ERC-8004 identity and reputation operations
• brickken rams: ERC-8226 mandate lifecycle, executor/compliance administration, reads, and EIP-712 signing
• brickken create-token: deploy an agentic ERC-20 through the x402 flow
• brickken mint: mint an agentic ERC-20 through the x402 flow
• brickken burn: burn an agentic ERC-20 through the x402 flow
• brickken approve: approve ERC-20 allowance through the x402 flow
• brickken transfer: transfer ERC-20 tokens through the x402 flow
• brickken transfer-from: transfer ERC-20 allowance through the x402 flow
• brickken tx: raw prepare, sign, send, status, and one-shot execute flows

RAMS Mandate Flow

brickken rams exposes ten write commands, five authenticated read commands, and local EIP-712 signing. Writes prepare only by default; add --execute to sign/send and settle x402.

Fetch typed data and sign it with the principal key:

brickken rams sign \
  --operation grant-mandate \
  --chain 11155111 \
  --agent "$AGENT" \
  --principal "$PRINCIPAL" \
  --valid-until 1789000000 \
  --identity-ref "$IDENTITY_REF" \
  --asset "$ASSET" \
  --max-transaction-value 1000000 \
  --max-cumulative-value 5000000 \
  --action 0x23b872dd \
  --json > rams-signature.json

Then request Brickken-relayed execution (omit --signer-address; the backend supplies its operation signer):

brickken rams grant \
  --chain 11155111 \
  --agent "$AGENT" \
  --principal "$PRINCIPAL" \
  --valid-until 1789000000 \
  --identity-ref "$IDENTITY_REF" \
  --asset "$ASSET" \
  --max-transaction-value 1000000 \
  --max-cumulative-value 5000000 \
  --action 0x23b872dd \
  --signature "$(jq -r .signature rams-signature.json)" \
  --deadline "$(jq -r .deadline rams-signature.json)" \
  --execution-mode brickken-relayed \
  --execute --json

The private key configured for this second command authorizes the x402 payment; it does not need to be the principal key.

Inspect the resulting mandate with API-key auth:

brickken rams inspect --chain 11155111 --agent "$AGENT" --principal "$PRINCIPAL" --json

Run brickken rams --help and brickken rams <command> --help for the complete input surface. Lifecycle signature mode is supported only by grant, revoke, extend, and set-operator; executor and admin operations are never Brickken-relayed.

Raw Transaction Flow

Use brickken tx when you want full control over the payload or you need to call a specific backend method directly.

One-shot execution:

brickken tx prepare \
  --method agentCreateToken \
  --file token.json \
  --execute \
  --json

Supported agentic token methods include:

• agentCreateToken
• agentMintToken
• agentBurnToken
• agentTransferToken
• agentTransferFromToken
• agentApproveToken
• agentApprove as a CLI alias that normalizes to agentApproveToken

For manual control:

brickken tx prepare --method agentRegister --file agent-register.json --json
brickken tx sign --file prepared.json --json
brickken tx send --tx-id 0xPreparedTxId --signed-tx 0xSignedRawTx --json

| Command | Purpose | Typical usage | | --- | --- | --- | | brickken tx prepare | Prepare a raw transaction payload | Agentic methods and custom API V2 methods | | brickken tx sign | Sign a transaction locally | Manual debugging and step-by-step flows | | brickken tx send | Send signed transaction payloads | Manual debugging and step-by-step flows | | brickken tx status | Look up a broadcast transaction by hash | Post-send tracking |

For brickken tx prepare --execute, the CLI:

1. prepares the transaction with /prepare-transactions
2. signs locally with the configured private key
3. sends the signed payload to /send-transactions

Example:

brickken tx prepare \
  --method agentSetMetadata \
  --file metadata.json \
  --execute \
  --json

Keep using the explicit tx sign / tx send path when you want full manual control over each step or need to inspect the unsigned payload before broadcasting.

Configuration

Global flags:

• --env <forge|sandbox|production> (forge resolves to https://d4aqanatl1.execute-api.eu-west-1.amazonaws.com/forge)
• --base-url <url>
• --api-key <key>
• --private-key <key>
• --rpc-url <url>
• --env-file <path>
• --json

Environment variables:

• BRICKKEN_API_KEY or BKN_API_KEY (RAMS reads and typed-data only)
• BRICKKEN_PRIVATE_KEY or BKN_PRIVATE_KEY
• BRICKKEN_BASE_URL or BKN_BASE_URL
• BRICKKEN_RPC_URL or BKN_RPC_URL
• BRICKKEN_ENV or BKN_ENV

The CLI automatically loads .env from the current working directory unless --env-file is provided.

Build Locally

pnpm install
pnpm build
node dist/index.js --help