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

# Build and deploy a contract

> Have your agent create a contract project with `stellar contract init`, build, deploy, and invoke it, and use the `AGENTS.md` file the project ships with.

Have your agent create a contract project, build it, deploy it to testnet, and call it. The project comes with an `AGENTS.md` file that tells your agent how to work in it.

## Ask your agent

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Create a Stellar contract project called my-project, build it, deploy it to testnet from agent-1, and call its hello function.
```

## Before you start

* Follow the [Quickstart](https://developers.stellar.org/docs/tools/cli/agent-cli/quickstart.md) first. `stellar contract init` writes `AGENTS.md` from `stellar-cli` 28.0.0 on.
* Install Rust 1.84 or later and the `wasm32v1-none` target with `rustup target add wasm32v1-none`. Rust 1.82 and 1.83 cannot build contracts.
* Fund a testnet identity, for example `agent-1` from the Quickstart.

## Steps

1. Create the project:

   ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
   stellar contract init my-project
   cd my-project
   ```

   This writes a Cargo workspace with one contract in `contracts/hello-world`, plus `README.md` and `AGENTS.md` at the workspace root. Pass `--name <NAME>` for a different contract name.

2. Build every contract in the workspace:

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

   The WASM file lands at `target/wasm32v1-none/release/hello_world.wasm`. The file name uses `_` where the package name has `-`. Add `--package <NAME>` to build one contract.

3. Deploy the contract and save an alias for it:

   ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
   ID=$(stellar contract deploy --wasm target/wasm32v1-none/release/hello_world.wasm --source agent-1 --network testnet --alias hello_world)
   ```

   stdout is the contract ID alone, on one line. `--alias` replaces an existing alias of the same name without asking, and warns about it on stderr.

   Inside a workspace you can leave out `--wasm`. `deploy` then builds first, deploys every contract, uses each package name as its alias, and prints one contract ID per line.

4. Call the contract:

   ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
   stellar contract invoke --id hello_world --source agent-1 --network testnet -- hello --to world
   ```

   stdout is the return value as one line of JSON, here `["Hello","world"]`. A function with no return value prints an empty line.

   `hello` only reads, so the CLI simulates the call and does not submit a transaction. It says so on stderr. Add `--send=yes` to submit it anyway. A call that writes state, emits an event, or needs authorization is submitted by default.

   To list a deployed contract's functions and their arguments, run `stellar contract invoke --id hello_world --network testnet -- -h`. It prints the list on stdout and exits with code 1, so do not treat that exit code as a failure.

## Read stdout, not `--output json`

`contract init`, `contract build`, `contract deploy`, and `contract invoke` have no `--output` flag. [Output and errors](https://developers.stellar.org/docs/tools/cli/agent-cli/reference/output-and-errors.md) lists the commands that do. Parse these four by stream:

| Command | stdout | stderr |
| - | - | - |
| `contract init` | Nothing | Each file it writes or skips |
| `contract build` | Nothing to parse | Cargo progress and the build summary |
| `contract deploy` | The contract ID | Upload and deploy progress, and the alias warning |
| `contract invoke` | The return value as JSON | Simulation and submission progress |

Keep the two streams apart. `2>&1` mixes progress lines into the value you parse. A failure prints `❌ error: ...` on stderr and exits non-zero, so check the exit code before you read stdout.

## The generated `AGENTS.md`

`stellar contract init` writes `AGENTS.md` at the workspace root. It is a short Markdown brief for coding agents. It covers:

* **Layout:** the workspace `Cargo.toml`, and each contract's `src/lib.rs` and `src/test.rs` under `contracts/<name>/`.
* **Build:** `stellar contract build`, where the WASM files land, and `--package` for one contract. It tells the agent not to use `cargo build --target wasm32v1-none`, because `stellar contract build` applies the flags and metadata the network expects.
* **Toolchain:** the `wasm32v1-none` target and Rust 1.84 or later.
* **Test:** `cargo test`, or `cargo test -p <name>` for one contract.
* **Deploy and invoke:** testnet commands for the sample `hello` function, and `-- -h` to list a deployed contract's functions.
* **Further reading:** links to the smart contract docs and soroban-examples.

The template lives in the CLI source at [`contract-workspace-template/AGENTS.md`](https://github.com/stellar/stellar-cli/blob/v28.1.0/cmd/soroban-cli/src/utils/contract-workspace-template/AGENTS.md).

`AGENTS.md` describes this project. [`stellar skill`](https://developers.stellar.org/docs/tools/cli/agent-cli/skills) describes the CLI itself. Give your agent both.

### How agents pick it up

`AGENTS.md` follows the [AGENTS.md](https://agents.md) convention. Agents that support it read the file when they work in the project, so there is nothing to install or run. If your agent reads a different instructions file, add a line there that points to `AGENTS.md`.

The file is a copy made when you ran `init`. It does not change when you upgrade the CLI.

### Customize it

`AGENTS.md` is a plain file in your project. Edit it and commit it with the rest of your code. Useful changes:

* Replace the `hello` sample with your own contract names, functions, and arguments.
* Name the identity and network the agent must use, for example `--source agent-1 --network testnet`.
* Add your own rules, for example "run `cargo test` before every deploy".

A rule in `AGENTS.md` is an instruction to the agent, not a limit the CLI enforces. To limit what an agent can spend, see [Delegate spending](https://developers.stellar.org/docs/tools/cli/agent-cli/guides/delegate-spending.md).

Running `init` again keeps your edits. For example, `stellar contract init . --name increment` adds a contract and skips every file that already exists, `AGENTS.md` included. `--overwrite` replaces every template file, `AGENTS.md` included, so save your changes before you use it.

## Related pages

* [Skills](https://developers.stellar.org/docs/tools/cli/agent-cli/skills.md)
* [Output and errors](https://developers.stellar.org/docs/tools/cli/agent-cli/reference/output-and-errors.md)
* [Hello World](https://developers.stellar.org/docs/build/smart-contracts/getting-started/hello-world.md)
* [Stellar CLI Manual](https://developers.stellar.org/docs/tools/cli/stellar-cli.md)