Overview

Relevant source files

• .github/workflows/publish.yml
• Cargo.lock
• Cargo.toml
• FULL_HELP_DOCS.md
• Makefile
• README.md
• cmd/crates/soroban-test/tests/fixtures/bye/Cargo.toml
• cmd/crates/soroban-test/tests/fixtures/hello/Cargo.toml
• cmd/crates/soroban-test/tests/fixtures/test-wasms/constructor/Cargo.toml
• cmd/crates/soroban-test/tests/fixtures/test-wasms/custom_account/Cargo.toml
• cmd/crates/soroban-test/tests/fixtures/test-wasms/custom_type/Cargo.toml
• cmd/crates/soroban-test/tests/fixtures/test-wasms/empty_constructor/Cargo.toml
• cmd/crates/soroban-test/tests/fixtures/test-wasms/hello_world/Cargo.toml
• cmd/crates/soroban-test/tests/fixtures/test-wasms/swap/Cargo.toml
• cmd/crates/soroban-test/tests/fixtures/test-wasms/token/Cargo.toml
• cmd/crates/soroban-test/tests/it/init.rs
• cmd/crates/soroban-test/tests/it/integration/secure_store.rs
• cmd/soroban-cli/README.md
• cmd/soroban-cli/src/commands/contract/mod.rs
• cmd/soroban-cli/src/commands/mod.rs
• cmd/stellar-cli/README.md
• install.sh
• prettier.config.js

Purpose and Scope

This document provides a high-level overview of the stellar-cli repository, a command-line tool for interacting with the Stellar blockchain network and deploying/managing Soroban smart contracts. It introduces the repository's architecture, major components, and organizational structure. For detailed information about specific subsystems, refer to:

• Workspace structure and crate organization: Workspace Structure and Dependencies
• CLI binary relationship: Package Structure and CLI Binaries
• Command parsing and execution: Core CLI Architecture
• Configuration management: Configuration System
• Contract lifecycle operations: Contract Operations
• Transaction handling: Transaction Management
• Key and identity management: Identity and Network Management

What is stellar-cli

stellar-cli is a Rust-based command-line interface that provides comprehensive tooling for Stellar blockchain development and operations. The repository produces two main binaries—stellar and soroban—that share the same underlying implementation but present different command structures for backward compatibility. The CLI enables developers to:

• Generate and manage cryptographic identities and accounts
• Build, deploy, and interact with Soroban smart contracts written in Rust
• Execute transactions and monitor network events
• Manage contract data lifecycle and archival storage
• Generate client bindings for contracts in multiple languages
• Operate local development networks via containers

The tool integrates with Stellar's RPC servers and history archives to provide both local simulation and live network interaction capabilities.

Sources: README.md1-113 FULL_HELP_DOCS.md1-46 cmd/soroban-cli/src/commands/mod.rs31-68

Repository Organization

Workspace Structure

The repository is organized as a Cargo workspace containing 24+ crates. The workspace configuration resides in Cargo.toml1-138 and defines shared dependencies, version constraints, and build profiles. Key organizational elements:

Component	Path	Purpose
Main Binaries	cmd/stellar-cli/, cmd/soroban-cli/	CLI entry points
Spec Tools	cmd/crates/soroban-spec-tools/	Contract specification parsing and code generation
Binding Generators	cmd/crates/soroban-spec-{json,typescript}/	Multi-language client generation
Testing Infrastructure	cmd/crates/soroban-test/	Integration testing framework
Test Contracts	cmd/crates/soroban-test/tests/fixtures/test-wasms/	WASM fixtures for testing
Hardware Wallet	cmd/crates/stellar-ledger/	Ledger device integration

The workspace uses resolver version 2 and defines shared dependencies for the Stellar SDK ecosystem, including soroban-sdk, stellar-xdr, and soroban-rpc packages. Dependencies are versioned at workspace level to ensure consistency across all crates.

Sources: Cargo.toml1-138 Makefile1-90

Command-Line Interface Architecture

Command Structure

The CLI is built using the clap crate with derive macros for argument parsing. The Root struct at cmd/soroban-cli/src/commands/mod.rs70-84 serves as the entry point, containing:

• global_args: Configuration options like --config-dir, --filter-logs, --quiet, --verbose
• cmd: An enum of all top-level command variants

The Cmd enum at cmd/soroban-cli/src/commands/mod.rs157-230 defines 13 top-level command categories, each mapped to a dedicated subcommand module. Commands follow a consistent pattern:

1. Parse arguments using clap::Parser derive macros
2. Validate inputs and resolve configuration
3. Execute async operations via trait implementations
4. Handle errors with typed error enums

The Root::run() method at cmd/soroban-cli/src/commands/mod.rs114-147 dispatches to appropriate subcommand handlers, with special logic for deprecation warnings and plugin fallback when encountering unknown subcommands.

Sources: cmd/soroban-cli/src/commands/mod.rs1-301 FULL_HELP_DOCS.md41-77

Core Subsystem Categories

The CLI functionality is organized into six major subsystem categories, each providing a distinct set of capabilities:

1. Contract Operations

The contract subcommand family at cmd/soroban-cli/src/commands/contract/mod.rs21-94 provides the complete smart contract development lifecycle:

Subcommand	Module	Purpose
init	init::Cmd	Scaffold new contract projects with templates
build	build::Cmd	Compile Rust contracts to WASM
upload	upload::Cmd	Install WASM to network ledger
deploy	deploy::wasm::Cmd	Instantiate contract from WASM
invoke	invoke::Cmd	Call contract functions with dynamic CLI
extend	extend::Cmd	Extend TTL for contract storage
restore	restore::Cmd	Restore archived contract data
fetch	fetch::Cmd	Download WASM from network
bindings	bindings::Cmd	Generate client code for multiple languages

2. Identity Management

The keys subcommand manages cryptographic identities with support for multiple storage backends (local files, OS secure stores, hardware wallets). See Identity and Network Management for details.

3. Network Operations

The network subcommand configures RPC endpoints, network passphrases, and manages network aliases. The container subcommand starts local Stellar networks using Docker containers for testing.

4. Transaction Management

The tx subcommand family provides low-level transaction construction, simulation, and submission with support for all 23+ Stellar operation types. See Transaction Management for details.

5. Event Monitoring

The events command streams contract events from the network with topic filtering and wildcard support. See Additional Features and Utilities for details.

6. Development Tools

Additional utilities include:

• snapshot: Download ledger state from history archives
• xdr: Encode/decode Stellar XDR structures
• cache: Manage transaction and contract spec cache
• doctor: Diagnose CLI and network issues

Sources: cmd/soroban-cli/src/commands/contract/mod.rs1-221 cmd/soroban-cli/src/commands/mod.rs157-230

Configuration and Storage Model

The CLI uses a hierarchical configuration system with multiple precedence levels. Configuration is stored in TOML files within either the global directory (~/.config/stellar/ or $XDG_CONFIG_HOME/stellar) or a local project directory (.stellar/).

Configuration components include:

• Identities: Named keypairs with multiple storage backend options
• Networks: Named RPC endpoints with network passphrases
• Contract Aliases: Human-readable names mapped to contract IDs per network

The global::Args struct at cmd/soroban-cli/src/commands/mod.rs79-80 carries global configuration options throughout command execution. The --config-dir flag allows overriding the default configuration location.

Sources: cmd/soroban-cli/src/commands/mod.rs70-84 FULL_HELP_DOCS.md71-72

RPC Client and Network Interaction

The CLI communicates with Stellar networks through the RPC (Remote Procedure Call) interface using the soroban-rpc client library. The NetworkRunnable trait at cmd/soroban-cli/src/commands/mod.rs290-301 defines a common pattern for commands that interact with RPC servers:

RPC-dependent commands receive configuration through:

• --rpc-url: Direct RPC endpoint specification
• --network: Named network lookup from configuration
• --network-passphrase: Network identifier for transaction signing
• --rpc-header: Custom HTTP headers for authentication

The RPC client handles transaction simulation, submission, and result polling, as well as querying ledger state and streaming events.

Sources: cmd/soroban-cli/src/commands/mod.rs290-301 FULL_HELP_DOCS.md130-166

Contract Specification and Dynamic CLI

A distinctive feature of stellar-cli is its "implicit CLI" generation system. When invoking contracts, the CLI:

1. Fetches the contract's specification (embedded in the WASM as custom sections)
2. Parses ScSpecEntry structures defining functions and types
3. Dynamically generates clap subcommands and arguments at runtime
4. Validates inputs against the contract's type system
5. Converts CLI arguments to XDR ScVal format

This approach eliminates the need for manual bindings while maintaining type safety. The contract spec tools at cmd/crates/soroban-spec-tools/ provide the parsing and validation logic. See Type System and Spec Tools for implementation details.

Sources: FULL_HELP_DOCS.md33-40 cmd/soroban-cli/src/commands/contract/mod.rs74-82

Build Profiles and Test Infrastructure

The workspace defines four build profiles at Cargo.toml123-136:

Profile	Optimization	Panic	Purpose
test-wasms	z (size)	abort	Minimal test contract binaries with LTO
release	Default	unwind	Production CLI binaries
release-with-panic-unwind	Default	unwind	Special debugging builds
debug	None	unwind	Development builds

The test-wasms profile specifically targets WASM contract compilation with aggressive size optimization (opt-level = "z") and link-time optimization (LTO) enabled to minimize contract deployment costs.

Test infrastructure includes:

• 8+ test WASM contracts in cmd/crates/soroban-test/tests/fixtures/test-wasms/
• soroban-test crate providing test environment abstractions
• Integration tests requiring live RPC servers
• Secure store integration tests for key management

Sources: Cargo.toml123-136 Makefile41-53 cmd/crates/soroban-test/tests/fixtures/test-wasms/hello_world/Cargo.toml1-18

Distribution Channels

stellar-cli is distributed through multiple channels:

Channel	Target	Installation Command
crates.io	Rust developers	cargo install stellar-cli
Homebrew	macOS/Linux users	brew install stellar-cli
GitHub Releases	All platforms	Binary downloads for 5 architectures
install.sh	Convenience	curl -fsSL ... | sh
Nix	Nix users	nix profile install github:stellar/stellar-cli
GitHub Actions	CI/CD	uses: stellar/[email protected]

The install.sh1-174 script provides an intelligent installation experience that detects the platform, downloads the appropriate binary, and handles sudo/user-level installation automatically.

GitHub Actions workflows at .github/workflows/publish.yml1-18 automate the release process, building binaries for:

• Linux x86_64 and aarch64
• macOS Intel and Apple Silicon
• Windows x64 with an Inno Setup installer

Sources: README.md26-73 install.sh1-174 .github/workflows/publish.yml1-18

Development Workflow Support

The repository provides comprehensive development workflow support through:

1. Makefile targets at Makefile1-90:

   • build-test-wasms: Compile test contracts
   • install: Install CLI and test fixtures
   • test: Run full test suite
   • rpc-test: Integration tests against live network
   • check: Lint and format checks
   • typescript-bindings-fixtures: Regenerate binding examples

2. Documentation generation: The doc-gen crate generates FULL_HELP_DOCS.md from CLI help text

3. Version management: Build-time injection of git commit hashes and version tags

4. Cross-platform builds: Support for macOS minimum version compatibility

The workspace structure facilitates development by allowing all crates to share dependencies while maintaining clear module boundaries.

Sources: Makefile1-90 Cargo.toml1-138