> ## Documentation Index
> Fetch the complete documentation index at: https://developers.stellar.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install the stellar CLI, connect it to your agent, fund a testnet key, and make your first agent-driven transfer.

## 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

You need `stellar-cli` 28.1.0 or later. That release adds the `stellar token` metadata, allowance, `transfer-from`, and burn subcommands and the `stellar skill` command these docs rely on. Follow [Install the Stellar CLI](https://developers.stellar.org/docs/tools/cli/install-cli.md), then confirm the version:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
stellar --version
```

### Check the environment

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Run `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 releases before 28.1.0.

## 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.

> [!WARNING]
>
> 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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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-1` and 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-1` a capped, expiring allowance with `stellar token approve`. The network enforces the cap. Use it when the funding account holds more than you want at risk.

[Delegate spending](https://developers.stellar.org/docs/tools/cli/agent-cli/guides/delegate-spending.md) walks through the allowance path, including how the agent spends it with `stellar token transfer-from`. [Authority model](https://developers.stellar.org/docs/tools/cli/agent-cli/reference/authority-model.md) 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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
stellar keys generate agent-2 --network testnet --fund
stellar keys address agent-2
```

Ask your agent:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Send 1 XLM from agent-1 to agent-2 on testnet, then show me the new balance.
```

It should run:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 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`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://developers.stellar.org/docs/tools/cli/agent-cli/reference/output-and-errors.md) before you build error handling, because only the `stellar token` family returns typed errors.

## Next steps

* [Send tokens](https://developers.stellar.org/docs/tools/cli/agent-cli/guides/send-tokens.md)
* [Delegate spending](https://developers.stellar.org/docs/tools/cli/agent-cli/guides/delegate-spending.md)
* [Authority model](https://developers.stellar.org/docs/tools/cli/agent-cli/reference/authority-model.md)