stellar-forge is a Rust CLI for manifest-driven Stellar workspaces.

It keeps desired project state in stellarforge.toml, persists observed deployment state in stellarforge.lock.json, generates scaffolds around contracts, and shells out to the official stellar CLI for chain-facing work.

Examples in this repository use stellar forge .... If plugin discovery is not available on your machine yet, replace every example with stellar-forge ....

stellar-forge is an orchestration layer for Stellar projects, not a replacement for the Stellar toolchain.

The split is:

• stellar-forge owns scaffolding, manifest parsing, validation, dry runs, lockfile updates, release planning, generated helper files, and project-oriented diagnostics
• stellar owns contract build/deploy/invoke, key management, alias management, local quickstart, and other low-level network primitives

That separation keeps the CLI focused on project structure and repeatable workflows.

Use this README for orientation. Use the docs folder for exact behavior.

Official Stellar references:

• Install Stellar CLI
• Stellar CLI plugins
• Contract lifecycle cookbook
• Working with assets and payments

The CLI currently covers:

• project bootstrap from templates such as minimal-contract, fullstack, issuer-wallet, merchant-checkout, rewards-loyalty, api-only, and multi-contract
• manifest-driven validation, synchronization, and release planning
• contract-oriented workspace flows including build, deploy, invoke, bindings, TTL, fetch, formatting, and linting
• classic wallet, SEP-7, relayer-aware, batch-payment, and smart-wallet workflows
• token flows for classic assets, SAC wrappers, contract tokens, and token-scoped airdrops
• generated API, OpenAPI, relayer, frontend, and event-ingestion scaffolds
• local development helpers, smoke checks, release history, drift, diff, rollback, and env export

For the full command surface, go straight to docs/command-reference.md.

These files define the project model:

The relationship between these files is documented in docs/manifest-reference.md.

The exact install commands for external tools may change over time, so prefer the official Stellar docs for those tools and use this README for how stellar-forge expects them to be available.

Release archives are published from tagged GitHub releases for:

• x86_64-unknown-linux-gnu
• aarch64-unknown-linux-gnu
• x86_64-apple-darwin
• aarch64-apple-darwin

For example, on Linux x86_64:

curl -L https://github.com/Pantani/stellar-forge/releases/download/v0.1.0/stellar-forge-0.1.0-x86_64-unknown-linux-gnu.tar.gz | tar -xz
install -m 0755 stellar-forge-0.1.0-x86_64-unknown-linux-gnu/stellar-forge ~/.local/bin/stellar-forge
stellar-forge doctor

cargo build --release
./target/release/stellar-forge doctor

After the relevant release channel has published:

cargo install stellar-forge
brew install Pantani/tap/stellar-forge
sudo snap install stellar-forge --classic
curl -1sLf 'https://dl.cloudsmith.io/public/pantani/stellar-forge/setup.deb.sh' | sudo -E bash
sudo apt-get install stellar-forge

Package-manager publishing for crates.io, Homebrew, APT via Cloudsmith, and Snap is wired through the release CI harness. See docs/release-publishing.md for channel readiness, required secrets, rerun behavior, and remaining external publish gates.

cargo install --path .
stellar-forge doctor

Once the stellar-forge binary is on PATH, the official Stellar CLI can discover it as the forge plugin:

stellar plugin ls
stellar forge doctor

If forge does not appear in stellar plugin ls, keep using stellar-forge ... directly until plugin discovery is working on your machine.

stellar forge init hello-stellar --template fullstack --network testnet
cd hello-stellar

Useful variants:

stellar forge init rewards-app --template rewards-loyalty
stellar forge init service-only --template api-only --no-install
stellar forge init contracts-only --template multi-contract --contracts 2 --no-api

Template reference:

stellar forge doctor
stellar forge project validate
stellar forge project info

stellar forge dev up
stellar forge dev reseed --network local
stellar forge project sync
stellar forge project smoke

What that gives you:

• local RPC and Horizon endpoints exported into .env.generated
• regenerated project files after manifest edits
• a repeatable local sandbox for tokens, contracts, and generated apps

stellar forge contract build
stellar forge --dry-run release plan testnet

stellar forge release deploy testnet
stellar forge release verify testnet
stellar forge release env export testnet

For the full release model, including drift, history, rollback, and registry flows, use docs/deployment-guide.md.

The generated workspace usually revolves around these paths:

If the template enables API and frontend scaffolds, a common loop is:

pnpm --dir apps/api install
pnpm --dir apps/api dev
pnpm --dir apps/web install
pnpm --dir apps/web dev
stellar forge project smoke
stellar forge project smoke --browser

Swap pnpm for npm, yarn, or bun if project.package_manager says otherwise.

The generated browser smoke runner is also available as split steps inside apps/web:

• smoke:browser:build
• smoke:browser:install
• smoke:browser:run

Those scripts are documented in more detail in docs/command-reference.md.

Local quality gates:

cargo fmt --all --check
cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
cargo test --locked
cargo audit

Contribution and project-process docs:

• CHANGELOG.md
• CONTRIBUTING.md
• SUPPORT.md
• SECURITY.md
• CODE_OF_CONDUCT.md

stellar-forge is licensed under the MIT License.

Make sure the stellar-forge binary is on PATH. Until plugin discovery works, use stellar-forge ... directly.

Install the official stellar CLI first, then rerun stellar forge doctor deps.

dev up expects [networks.local] to exist with kind = "local". It also needs Docker for the local network workflow.

That command needs the API scaffold and persisted storage. Run stellar forge events ingest init first, and make sure sqlite3 is installed locally.

Shared test environments can lose state. When ids in stellarforge.lock.json no longer resolve, redeploy or reseed the target environment and export runtime values again.