# Agents \[Operate Splits programmatically via the CLI, or connect AI tools over MCP] The Splits CLI operates Splits programmatically: query accounts, transactions, balances, and contacts; propose and sign transactions. It also runs as an MCP server for AI tools (Claude Code, Cursor, Amp). For an exhaustive reference of every flag, run `splits --help` or `splits --schema`. ## Quick start See the full command surface without installing: ```bash npx @splits/splits-cli@latest --llms ``` ## Get set up ### Get an API key Create a key in **Settings > API Keys** with the scopes you need: * **Read**: query data only * **Write**: create and propose transactions; update transaction memos and properties * **Owner**: manage members and edit other organization settings Copy the key (it starts with `sk_`) and save it somewhere secure. You won't be able to see it again. ### Install Install globally via npm: ```bash npm install -g @splits/splits-cli@latest ``` Or run without installing: ```bash npx @splits/splits-cli@latest ``` ### Sign in Sign in: ```bash splits auth login --api-key sk_... ``` This saves the key to a local config file. Verify your connection: ```bash splits auth whoami ``` This shows your team name, API key name, granted scopes, where the key came from (env vs. local config), and any local EOA signing key you've created. To remove the saved key, run `splits auth logout`. ## Inspect your org Read-only commands. None require Write or Owner scope. **Accounts and balances** * `splits accounts list`: list all accounts in your team * `splits accounts get
`: details for a specific account * `splits accounts balances
`: token balances (filter with `--chainIds 1,8453`) * `splits accounts chains
`: list chains an account is deployed or synced on * `splits accounts signers
`: list passkey and EOA signers with the current threshold **Transactions** * `splits transactions list`: list recent transactions. Filter by `--chainId`, `--account` (single address or comma-separated), `--direction` (`inbound` / `outbound`), `--minAmount` / `--maxAmount` (inclusive USD bounds, sign-agnostic), date range via `--startDate` / `--endDate` (ISO 8601; end date exclusive) or `--period` shorthand (`thisWeek`, `thisMonth`, `thisYear`, `lastWeek`, `lastMonth`, `lastYear`, `last30Days`, `last90Days`, `last6Months`), `--memo` (case-insensitive substring, min 3 chars), and `--limit` (max 200). Use `--cursor` from a previous response to paginate, replaying the same filters. Look up a single transaction with `--user-op-hash` or `--transaction-hash`. * `splits transactions get `: details for a specific transaction **Reference data** * `splits contacts list`: your team's contacts (search with `--q`) * `splits contacts lookup --addresses 0x...,0x...`: batch lookup (max 100 addresses) * `splits tokens metadata --address 0x... --chainId 1`: symbol, decimals, etc. * `splits tokens whitelist` / `splits tokens blocklist`: your team's token visibility lists * `splits chains list` / `splits chains get `: supported networks * `splits members list`: members of your org * `splits members signers `: passkey IDs for a member (used by `accounts create`) * `splits settings get`: your team's settings * `splits automations list`: your team's automations ## Transaction metadata * `splits transactions memo --memo "text"`: set or clear a memo (max 500 chars). * `splits transactions properties set --properties '{"k":"v"}'`: shallow-merge custom JSON metadata onto a transaction (≤ 500 chars minified). String values can also be set with repeatable `--property k=v` flags, and removed with `--unset k`. * `splits transactions properties replace --properties '{"k":"v"}'`: atomically replace all custom JSON metadata. * `splits transactions properties clear `: remove all custom JSON metadata. ## Propose transactions These commands create proposals that still need to be signed, either in the web UI or with `transactions sign` if you've registered an EOA. All require the **Write** scope. * `splits transactions create transfer --account 0x... --chainId 8453 --recipient 0x... --token 0x... --amount 100`: token transfer proposal. Amount is in human-readable units (e.g. `100` for 100 USDC, `0.5` for 0.5 ETH). Use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` for native ETH. Optional `--name`, `--memo`, `--properties`, `--validUntil` (default 7 days out, max 30). * `splits transactions create custom --account 0x... --chainId 8453 --calls '[{"to":"0x...","data":"0x..."}]'`: proposal with raw EVM calls (1–20 per transaction; each call takes optional `value` in wei). Use for any on-chain action: contract calls, approvals, swaps. Optional `--name`, `--memo`, `--validUntil`. * `splits transactions cancel `: cancel a pending proposal (only works on `CREATED` or `DRAFTED`). * `splits transactions update-gas-estimation `: refresh gas estimates. For multisig, run this when exactly one signer remains. ## Sign locally with an EOA By default, signing happens in the web UI with a passkey. To let an agent or automation operate headlessly, you can register a local EOA and sign from the CLI. The flow is: create or import a private key locally → register the address with the backend → attach it to a subaccount → sign proposals. **Manage the local key** * `splits auth create-key`: generate a new local Ethereum EOA in `~/.splits/config.json`. Pass `--register` to also register the address with the backend in one call. Refuses if a key already exists. * `splits auth import-key`: import an existing private key. Prefer stdin: `echo $PRIVATE_KEY | splits auth import-key`. The `--privateKey` flag is refused under MCP mode so it doesn't land in tool-call transcripts. * `splits auth delete-key`: remove the local key. Does **not** revoke it on-chain; use `accounts update-signers` (or the web app) to detach it from any subaccounts. **Register and attach** * `splits auth register-signer
`: register an EOA address with the backend so it can be attached as a signer. Idempotent: re-running with the same address returns the same id. * `splits auth signers`: list EOA signers registered under the acting user. Returns the ids needed by `accounts update-signers`. * `splits accounts update-signers
--addEoaSignerIds id1,id2 --threshold 2`: propose adding/removing signers (passkeys and/or EOAs) and/or changing the threshold on a subaccount. The proposal must be approved and signed in the web UI via the returned `signUrl`. Updates apply to every active network on the org automatically. Recovery / resetting signers stays web-only. Requires the **Owner** scope. **Sign** * `splits transactions sign `: sign a pending multisig transaction with the local EOA. Fetches the transaction's signing hash, produces a `personal_sign` signature locally, and submits it. Auto-submits the UserOp once threshold is met; pass `--noSubmit` to record the signature only. Retries once on a stale signer nonce. Requires the **Write** scope and a registered EOA attached to the account. ## Manage subaccounts and the org The account commands require the **Owner** scope. * `splits accounts create --name "Name" --threshold 2`: create a new subaccount. Add signers with `--passkeyIds` and/or `--eoaSignerIds` (or `--eoaAddresses`). * `splits accounts rename
--name "New Name"` * `splits accounts archive
` / `splits accounts unarchive
`: archive fails if the account has pending state changes. * `splits org create --email you@example.com`: start creating a new org; requires no API key. Sends a setup link to the email; complete creation in the web UI. (For a new account inside an existing org, use `accounts create` instead.) ## Tune output for agents By default the CLI prints human-readable tables; when piped or run under MCP, it prints JSON. Global flags reshape output further: * `--format `: pick a serialization. `toon` is a token-efficient format optimized for LLM context. * `--filter-output `: project specific paths from the output, e.g. `--filter-output "items[0,3].address,nextCursor"`. * `--token-count` / `--token-limit ` / `--token-offset `: measure or budget output tokens. Useful when chaining results into a model with a context limit. * `--schema`: print the JSON Schema for the current command's input. Helpful for code-generation and self-describing tool calls. * `--llms`: print an LLM-readable manifest of the entire CLI surface. Useful for bootstrapping new agents. ## Connect to AI tools (MCP) MCP (Model Context Protocol) lets AI tools call the CLI on your behalf. **Every CLI command is automatically exposed as an MCP tool**, including any new commands added later. ### Claude Code, Cursor, and other clients Auto-detect your client: ```bash splits mcp add ``` This works for Claude Code, Cursor, and other supported clients. To register manually with Claude Code: ```bash claude mcp add splits -e SPLITS_API_KEY=sk_... -- npx @splits/splits-cli --mcp ``` For any tool that supports MCP over stdio, run the CLI with the `--mcp` flag and pass the API key via `SPLITS_API_KEY`: ```bash SPLITS_API_KEY=sk_... npx @splits/splits-cli --mcp ``` ### Skills and shell completions * `splits skills add`: sync ready-made skill files (e.g. for Claude Code) so your agent has guidance for using the CLI effectively. * `splits completions`: generate a shell completion script. Source the output from your shell rc file. ### Verify the connection Once connected, ask your AI tool to run `splits auth whoami` to confirm. You should see your team name and API key scopes. ## Examples Things to try: * "Show me the balances for all my accounts on Base" * "What transactions happened in the last week?" * "Add a memo to transaction X saying 'Q1 contractor payment'" * "Tag the last 5 outbound transfers with property `category=payroll`" * "Which chains is this account deployed on?" * "Look up the metadata for this token address" * "Create a new subaccount called 'Treasury' with a 2-of-3 threshold" * "Send 100 USDC from my account on Base to 0x..." * "Create a proposal to call the distribute function on this contract" * "Set up a new org for [my-email@example.com](mailto\:my-email@example.com)" * "Find all outbound payments to Acme between $4,500 and $5,500 last month" * "Add my local EOA as a signer on the Treasury subaccount with a 2-of-3 threshold" * "Sign the pending transfer proposal with my local key"