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.

Verified against stellar-cli 28.1.0.

What You Ask Your Agent	What Your Agent Executes	How It Works Under the Hood
"Learn how to use the Stellar CLI"	stellar skill	Dumps structured CLI conventions directly into the agent’s prompt/context window.
"How much USDC is in alice's account?"	stellar token balance	Reads the balance in smallest units, or as a decimal with --decimal. No key setup needed.
"Send 20 USDC to G..."	stellar token transfer	Executes an onchain transfer and returns the transaction hash.
"Limit agent spending to 50 USDC"	stellar token approve	Grants a capped, time-bound allowance enforced directly onchain by the Stellar network.
"Draft a payment for my review"	stellar tx new payment --build-only	Builds 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): The stellar token commands return typed JSON, including transaction hashes and a typed error envelope. Coverage elsewhere varies, and tx send and tx new have no --output flag. Output and errors lists what each command supports.
• 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.

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 read the full Stellar CLI Manual.

Functional Area	What Your Agent Can Do	CLI Commands
System & Agent Context	Check environment health and load usage rules into LLM context windows.	stellar doctor stellar skill
Balances & Metadata	Read token holdings, inspect token names, symbols, and decimal precision.	stellar token balance stellar token decimals / name / symbol
Transfers & Payments	Move tokens and get back the transaction hash, as a bare line by default or as JSON with --output json.	stellar token transfer
Spending Limits	Set spending limits and audit active delegate approvals.	stellar token approve stellar token allowance
Transactions & Contracts	Build raw operations, deploy Soroban contracts, and invoke custom smart contracts.	stellar tx new <OP> stellar contract deploy / invoke
Safe Offline Operations	Draft 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 first two below are enforced by the network or by a human signer, not by the agent following instructions. The third is a convention your agent has to follow:

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.
• Delegate spending is the page to read before any real money is involved.
• Authority & Security Model 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.