Skip to main content

Stellar CLI for Agents

Use the Stellar CLI and CLI Skills to give your AI agents an agent-friendly wallet and native way to inspect, move, and manage assets on Stellar. After following the Quickstart to onboard your agent, you can use natural language to prompt your agent to use the Stellar CLI.

What You Ask Your AgentWhat Your Agent ExecutesHow It Works Under the Hood
"Learn how to use the Stellar CLI"stellar skillDumps structured CLI conventions directly into the agent’s prompt/context window.
"How much USDC is in alice's account?"stellar token balanceReads the balance in smallest units, or as a decimal with --decimal. No key setup needed.
"Send 20 USDC to G..."stellar token transferExecutes an onchain transfer and returns the transaction hash.
"Limit agent spending to 50 USDC"stellar token approveGrants a capped, time-bound allowance enforced directly onchain by the Stellar network.
"Draft a payment for my review"stellar tx new payment --build-onlyBuilds an unsubmitted transaction payload to a file for human sign-off or air-gapped execution.

Agent Ergonomics​

Browser wallets are hard for agents. The CLI provides four key agent primitive enhancements:

  • Unified Asset Resolution: Interacts with native XLM, SAC (Stellar Asset Contracts), or SEP-41 tokens using consistent identifiers (CODE:ISSUER, contract ID, or custom alias).
  • Self-Scaffolding Context: Running stellar contract init automatically generates an AGENTS.md guide in local project directories, giving LLMs instant awareness of local commands and tool rules.
  • Structured JSON Outputs (--output json): Dumps typed JSON payloads containing status codes, execution results, and transaction hashes instead of plain text stdout.
  • Onchain Diagnostic Errors: When a transaction reverts, the CLI returns the contract's diagnostic event trail inside the error envelope. Agents can read why a transaction failed and auto-correct parameters.

Capability Surface​

Beyond only using the Stellar CLI as a wallet, your agent can also use the full power of CLI to interact with, build, and deploy contracts. Humans can check out full CLI docs here.

Functional AreaWhat Your Agent Can DoCLI Commands
System & Agent ContextCheck environment health and load usage rules into LLM context windows.stellar doctor
stellar skill
Balances & MetadataRead token holdings, inspect token names, symbols, and decimal precision.stellar token balance
stellar token decimals / name / symbol
Transfers & PaymentsMove tokens and get back the transaction hash, as a bare line by default or as JSON with --output json.stellar token transfer
Onchain GovernanceSet spending limits and audit active delegate approvals.stellar token approve
stellar token allowance
Transactions & ContractsBuild raw operations, deploy Soroban contracts, and invoke custom smart contracts.stellar tx new <OP>
stellar contract deploy / invoke
Safe Offline OperationsDraft unsigned transactions for human-in-the-loop approval workflows.stellar tx new <OP> --build-only

Safety Architecture​

Giving an agent financial execution power requires hard guardrails. The CLI relies on protocol-level constraints rather than prompt compliance:

  1. Protocol Allowance Enforcement: Primary funds remain in your treasury account. Issue your agent a capped allowance using stellar token approve. If the agent attempts to overspend, the Stellar ledger rejects the transaction.
  2. Human Approval Workflows: Use --build-only flags on sensitive transactions. Your agent formats the payload into a file, leaving final signing authority to a human or air-gapped machine.
  3. Explicit Smallest-Unit Amounts: token transfer and token approve take --amount in the token's smallest unit and do no conversion. Read stellar token decimals first and have the agent show its arithmetic before it sends.

Where to go next​

  • Skills covers stellar skill, the built-in guide that teaches your agent the CLI's conventions.
  • Give your agent a spending limit is the page to read before any real money is involved.
  • What bounds your agent is explicit about what the CLI does not protect you from.
  • Architecture covers how the read and write paths differ, where state lives, and how to split building, signing, and submitting across machines.
  • Output and errors covers which commands emit structured JSON your agent can branch on, because the coverage is not uniform.
  • Troubleshooting for when something does not work.