This document provides a high-level introduction to the stellar-cli repository, which contains the unified command-line interface for interacting with the Stellar network and developing Soroban smart contracts. It covers the project's purpose, binary structure, command organization, and core architectural components.
For detailed information about specific subsystems:
The stellar-cli repository provides the stellar command-line tool (also aliased as soroban), which serves as the primary interface for:
The CLI is distributed through multiple channels: Homebrew, cargo install, binary releases on GitHub, and as a GitHub Action. It supports macOS, Linux, and Windows across x86_64 and ARM64 architectures.
Sources: README.md1-113 FULL_HELP_DOCS.md1-48 cmd/soroban-cli/src/commands/mod.rs32-47
The repository produces two binary executables that share the same underlying implementation:
| Binary | Source Path | Purpose | Status |
|---|---|---|---|
stellar | cmd/stellar-cli/src/bin/stellar.rs | Primary CLI interface | Preferred |
soroban | cmd/soroban-cli/src/bin/soroban.rs | Legacy alias | Maintained for compatibility |
Both binaries execute identical code from the soroban-cli library crate at cmd/soroban-cli/src/lib.rs The stellar-cli package at cmd/stellar-cli/Cargo.toml1-30 is a thin wrapper that re-exports soroban-cli functionality.
Sources: cmd/soroban-cli/Cargo.toml15-21 cmd/stellar-cli/Cargo.toml15-18 cmd/stellar-cli/README.md1-31
The CLI is organized around the Root struct defined at cmd/soroban-cli/src/commands/mod.rs79-85 which dispatches to specialized command modules:
Sources: cmd/soroban-cli/src/commands/mod.rs159-236 FULL_HELP_DOCS.md43-63
| Command Category | Module Path | Primary Functions |
|---|---|---|
| Contract Operations | cmd/soroban-cli/src/commands/contract/mod.rs1-221 | Build, deploy, invoke, extend, restore contracts |
| Identity Management | commands::keys | Generate keys, manage identities, secure storage |
| Network Configuration | commands::network | Configure RPC endpoints, network presets |
| Transaction Building | commands::tx | Construct, sign, simulate, send transactions |
| Event Streaming | commands::events | Watch and filter contract events |
| Snapshot Management | commands::snapshot | Download ledger snapshots from archives |
| Developer Tools | commands::doctor, commands::cache | Diagnostics, caching, troubleshooting |
Sources: cmd/soroban-cli/src/commands/mod.rs8-25 cmd/soroban-cli/src/commands/contract/mod.rs21-94
The CLI supports the complete contract development workflow:
Key Features:
invoke command generates contract-specific CLIs on-the-fly from contract specifications (FULL_HELP_DOCS.md74-82)__constructor functions during deploymentcontainer commandsSources: FULL_HELP_DOCS.md79-104 cmd/soroban-cli/src/commands/contract/mod.rs21-94
Sources: cmd/soroban-cli/Cargo.toml37-49 FULL_HELP_DOCS.md126-137
The repository is structured as a Cargo workspace containing 23+ crates. The primary crates are:
| Crate | Location | Purpose |
|---|---|---|
soroban-cli | cmd/soroban-cli/ | Core CLI implementation and command handlers |
stellar-cli | cmd/stellar-cli/ | Thin wrapper producing stellar binary |
soroban-test | cmd/crates/soroban-test/ | Testing framework and utilities |
soroban-spec-tools | cmd/crates/soroban-spec-tools/ | Spec parsing and type conversion |
soroban-spec-typescript | cmd/crates/soroban-spec-typescript/ | TypeScript binding generation |
soroban-ledger-snapshot | cmd/crates/soroban-ledger-snapshot/ | Snapshot downloading and management |
stellar-ledger | cmd/crates/stellar-ledger/ | Ledger hardware wallet integration |
Dependencies: The CLI depends on key Stellar ecosystem crates including stellar-xdr, soroban-sdk, stellar-strkey, and soroban-rpc as specified in cmd/soroban-cli/Cargo.toml38-49
Sources: cmd/soroban-cli/Cargo.toml1-145 cmd/stellar-cli/Cargo.toml1-30 cmd/crates/soroban-test/Cargo.toml1-61
The CLI supports conditional compilation through feature flags:
The additional-libs feature (enabled by default) includes:
Users can build without these dependencies using cargo install --no-default-features.
Sources: cmd/soroban-cli/Cargo.toml32-36 README.md52-56
The build process is managed through a Makefile with multiple targets:
Key Build Targets:
make build-test-wasms: Compiles test WASM contracts at Makefile41-42make check: Runs linters and formatters at Makefile59-62make test: Executes unit and integration tests at Makefile50-53make rpc-test: Runs integration tests against a local RPC server at Makefile56-57Sources: Makefile1-90 cmd/soroban-cli/Cargo.toml1-145
Installation Methods:
curl -fsSL https://github.com/stellar/stellar-cli/raw/main/install.sh | sh (install.sh1-174)brew install stellar-cli (README.md43)cargo install --locked stellar-cli (README.md49)uses: stellar/stellar-cli@v23.0.1 (README.md71)Sources: README.md26-73 install.sh1-174 .github/workflows/publish.yml1-18
The root command execution follows this pattern:
The Root::run() method at cmd/soroban-cli/src/commands/mod.rs115-149 performs the dispatch:
Sources: cmd/soroban-cli/src/commands/mod.rs87-157
All command errors are aggregated into the root Error enum at cmd/soroban-cli/src/commands/mod.rs238-297 which uses thiserror for error propagation. This allows structured error handling across all command modules while providing user-friendly error messages.
Sources: cmd/soroban-cli/src/commands/mod.rs238-297 cmd/soroban-cli/src/commands/contract/mod.rs96-145
The CLI integrates with multiple external systems:
| System | Integration Point | Purpose |
|---|---|---|
| Stellar RPC | soroban-rpc crate | Transaction simulation, submission, event streaming |
| History Archive | soroban-ledger-snapshot crate | Ledger snapshot downloads |
| Docker | bollard crate | Local network containers via container commands |
| OS Keychain | keyring crate (optional) | Secure key storage |
| Ledger Wallet | stellar-ledger crate (optional) | Hardware wallet signing |
| Stellar Lab | --sign-with-lab flag | Browser-based transaction signing |
Sources: cmd/soroban-cli/Cargo.toml76-128
The CLI uses a hierarchical configuration system with five priority levels (detailed in Configuration System):
config.toml defaultsConfiguration files are stored in ~/.config/stellar/ (or $XDG_CONFIG_HOME/stellar/) with separate subdirectories for identities, networks, and contract aliases.
Sources: cmd/soroban-cli/src/commands/mod.rs6 FULL_HELP_DOCS.md72
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.