Quickstart
Before you start
You need a terminal on macOS, Linux, WSL, or Windows, and an AI agent that can run shell commands (Claude Code, Codex, Cursor, or similar). Contract development also needs the wasm32v1-none target, but nothing on this page does.
Every command below targets testnet, where friendbot funds accounts for free. Move to mainnet after you have watched your agent work.
Step 1: Install the CLI
The agentic experience around the Stellar CLI is currently in developer preview.
Some features are merged to main but not yet in a release, so you build the CLI from GitHub main instead of installing a release. Once they ship, use a release install.
You need Rust 1.93.0 or later (rustc --version), Cargo, and Git. A cold build takes 5 to 15 minutes. The repository pins Rust in rust-toolchain.toml, but cargo install ignores that pin and uses your default toolchain, so check it yourself. Update with rustup update stable, or install Rust from rustup.rs.
cargo install --locked --git https://github.com/stellar/stellar-cli --branch main stellar-cli \
--root ~/.stellar-main
Keep both flags. Without --branch main, cargo can resolve the default branch from its cached git database and install an old commit while still reporting success (we got 23.1.3 from September 2025 this way). --root ~/.stellar-main keeps the build from colliding with a release install, since both binaries are named stellar.
Confirm you have the main build:
~/.stellar-main/bin/stellar token decimals --help
A main build prints help. A release prints error: unrecognized subcommand 'decimals' and exits 2. --version cannot tell them apart, because both report 28.0.0.
Bare stellar usually resolves to a release install, which handles everything except those five subcommands. Call the main build by its full path wherever these docs need it.
Release installs
To install a release, follow Install the Stellar CLI. Pin an explicit version in CI. Homebrew and the install script track latest, so a green build today can be red tomorrow.
Check the environment
stellar doctor
stellar doctor reports your CLI version, Rust toolchain, secure store and Ledger availability, config paths, and the reachability of every configured network. It does not check account funding, API keys, or contract health. Run it first whenever something later fails.
Step 2: Tell your agent to load the Stellar skill
Ask your agent to load the CLI's conventions:
Run `~/.stellar-main/bin/stellar skill` and follow its conventions for every stellar command in this session.
stellar skill prints a short Markdown guide covering network use, keys use, contract aliases, --send=no for reads, and the stdout-versus-stderr split. It does not cover the stellar token family, tx new, message signing, or spend authority. The guides in these docs cover those. It exits 2 on a release install, so point the agent at the main build.
Step 3: Create a key for your agent
Give the agent its own identity rather than sharing yours, so its transactions come from an account you fund separately and can see in isolation.
Keys are stored locally on your device, and nothing stops your agent from reaching them. It runs as your user, so it can read ~/.config/stellar/identity/, run stellar keys secret to print a secret key or seed phrase, or sign with any identity on the machine, including yours. --secure-store keeps the seed out of a plaintext file, but the agent can still use it through the CLI. Keep only what you are willing to lose in any identity on a machine your agent runs on.
stellar keys generate agent-1 --network testnet --fund
Pass --fund or the account is created locally but never funded on the network. The first command that needs it then fails with Error(Contract, #6), "account entry is missing", which names neither funding nor --fund. The words trustline, trust, and fund do not appear in that error at all. Fix it with stellar keys fund <NAME> --network testnet.
Check the address and balance:
stellar keys address agent-1
stellar token balance --id native --account agent-1 --network testnet --decimal
Where the key is stored
Without --secure-store, identities are written in plaintext to ~/.config/stellar/identity/<NAME>.toml. Add the flag to keep the seed phrase in your OS keychain instead:
stellar keys generate agent-1 --network testnet --fund --secure-store
Secure store supports seed phrases only, not raw secret keys.
A --secure-store identity's .toml file holds no key material, only entry_name and public_key. The seed phrase itself lives in the OS keychain, and the CLI needs this file's pointer to reach it. The file looks harmless because it contains nothing secret, which is exactly what makes it dangerous: deleting it does not delete the key, but it does strand the account, since the CLI can no longer find where the key lives. Remove a secure-store identity with stellar keys rm <NAME> --force, which purges both the file and the keychain entry, never by deleting the file by hand. If you have already deleted the file, recreate it with the same entry_name and public_key and the CLI can sign again.
There is no stellar keys rename. To rename an identity, move its file in ~/.config/stellar/identity/ and confirm with stellar keys address that the public key is unchanged.
Step 4: Choose how your agent holds funds
Pick one. This is the decision that determines your exposure.
- Own key. The agent holds
agent-1and spends from it directly. Simple, and bounded only by that account's balance. Use it on testnet and for small mainnet amounts. - Allowance. You keep funds in an account the agent does not control, and grant
agent-1a capped, expiring allowance withstellar token approve. The network enforces the cap. Use it when the funding account holds more than you want at risk.
Delegate spending walks through the allowance path, including the extra contract invoke step needed to actually spend it. stellar token has no command that draws on an allowance by itself. Authority model explains what neither option protects you from.
Step 5: Set your defaults
This step is for you, not your agent. These defaults are machine-wide, so every other repository on this machine picks them up.
stellar network use testnet
stellar keys use agent-1
stellar env
stellar env shows what the CLI will use, with secrets concealed (--reveal prints them, 27.0.0 and later).
Your agent should ignore saved defaults and pass --network and a source flag on every command, because it cannot see what an earlier session saved. The source flag varies. The tx and contract families take --source. stellar token transfer and token approve take --from and reject --source. stellar keys commands take the identity name as a positional argument and have no source flag.
In CI, set environment variables instead:
export STELLAR_NETWORK=testnet
export STELLAR_ACCOUNT=agent-1
export STELLAR_NO_CACHE=true
Step 6: Make your first transfer
Create a second identity to send to:
stellar keys generate agent-2 --network testnet --fund
stellar keys address agent-2
Ask your agent:
Send 1 XLM from agent-1 to agent-2 on testnet, then show me the new balance.
It should run:
stellar token transfer --id native --from agent-1 --to <ADDRESS> --amount 10000000 --network testnet
stellar token balance --id native --account agent-1 --network testnet --decimal
--amount is in the token's smallest unit, so 10000000 is 1 XLM at 7 decimals. Other tokens differ, so read the value with ~/.stellar-main/bin/stellar token decimals --id <TOKEN>.
Nothing checks the amount for you. --amount 1 sends 0.0000001 XLM, and --amount 0 moves nothing but still charges the fee. Both exit 0 and report tx_success. The balance check is what catches this: agent-1 should fall by 1 XLM plus the fee.
token transfer pays Soroban resource fees, roughly 9,500 to 14,500 stroops on testnet against 100 for a classic payment, and takes no fee flag. When you need a capped fee or an unsigned envelope, use the classic path, which also rejects --amount 0:
stellar tx new payment --source agent-1 --destination <ADDRESS> --amount 10000000 \
--network testnet --inclusion-fee 200
Step 7: Verify what your agent did
A submitted transfer prints its hash as the last line of stdout (or in tx_hash with --output json). Look it up with --hash:
TX=$(stellar token transfer --id native --from agent-1 --to <ADDRESS> --amount 10000000 --network testnet)
stellar tx fetch result --hash "$TX" --network testnet
Never retry a timed-out write blindly. On transaction submission timeout the RPC accepted the transaction but never reported a final status, so the outcome is unknown. It can still land later. The command exits 1 and $TX can be empty, exactly like a real failure. Take the hash from the stderr line ℹ️ Signing transaction: <HASH> (text mode only, since JSON mode writes nothing to stderr) and check stellar tx fetch result --hash <HASH>. If it is still not found, read both balances and the source account's sequence number before you decide. Only rebuild the payment once you have confirmed the first one did not land.
An error starting with ❌ that names a cause (TxBadAuth, TxBadSeq, a rejected simulation) is a real failure and safe to retry. See Output and errors before you build error handling, because only the stellar token family returns typed errors.