CLI Commands

Stellar Scaffold provides several CLI commands to help manage your Stellar smart contract development.

Init Command

Initialize a new Stellar Scaffold project:

stellar scaffold init <project-path>

Options:

• project-path: Required. The path where the project will be created
• --template <name>: Template selector. A bare framework name (react or svelte) picks an official template; a user/repo shorthand (optionally with #branch or #tag) degits that community repo directly; none creates a contracts-only project with no frontend. Omit to choose interactively
• --no-template: Create a contracts-only project with no frontend (alias for --template none)
• --tutorial: Start from the simplified project the tutorial builds on, rather than a full template
• -p <name> or --package-manager <name>: Package manager to use, recorded as project.package-manager in scaffold.yml. Omit to choose interactively
• -y or --yes: Accept all defaults and skip interactive prompts

--tutorial picks the frontend and the package manager for you, so it does not prompt. Pass --package-manager alongside it if you want something other than npm.

The init command creates:

• A new Stellar smart contract project with best practices and configurations
• A frontend application in app/, in the framework you chose
• app-lib/, utility code your app can use for wallet connection, network settings, and formatting, plus the directory your generated contract clients are written to
• Configuration files for both contract and frontend development

Official templates come from the Stellar Scaffold templates repo. To build your own, see Community Templates.

With --no-template (or --template none), the frontend layer is omitted entirely: no app/, no app-lib/, no JS workspaces, no dependency install. Every contract in scaffold.yml is written with client: false, so stellar scaffold build --build-clients and watch deploy contracts without generating TypeScript clients. Remove it from a contract if you later need one.

Generate Command

Generate a new contract from examples or wizard. Have a look at their official documentation.

stellar scaffold generate contract [options]

Options:

• --from <example>: Clone a contract from one of two example sets, selected by prefix:
  • oz/<name> — an OpenZeppelin stellar-contracts example, e.g. --from oz/nft-royalties
  • stellar/<name> — a soroban-examples contract, e.g. --from stellar/hello-world
• --ls: List available contract examples
• --from-wizard: Open the OpenZeppelin Contract Wizard in your browser
• -o <output> or --output <output>: Output directory for the generated contract (defaults to contracts/<example-name>)
• --force: Overwrite the destination path if it already exists

The generate command downloads the example, caches it locally, writes it to contracts/<example-name>/, and merges the dependencies it needs into your workspace Cargo.toml. Each example set is pinned to a supported release rather than tracking upstream main, so the version you get is the one this CLI release was tested against.

generate does not add the contract to scaffold.yml. Add an entry under contracts: yourself, with type: workspace, the crate's package name as source, its constructor args, and the networks it belongs on. See Configuration.

Upgrade Command

Transform an existing Soroban workspace into a full scaffold project:

stellar scaffold upgrade [workspace-path]

Options:

• workspace-path: Path to existing workspace (defaults to current directory)

The upgrade command:

• Validates the existing workspace (requires Cargo.toml and contracts/ directory)
• Downloads and integrates the frontend template
• Generates environments.toml with discovered contracts. This is the legacy config format; see Configuration to move it to scaffold.yml version 2
• Analyzes contracts for constructor arguments and prompts for configuration
• Preserves all existing contract code and project structure
• Adds development tools and configurations

Requirements for upgrade:

• Must have a Cargo.toml file in the workspace root
• Must have a contracts/ directory with Soroban contracts
• Contracts should be properly configured as cdylib crates

Build Command

Build contracts and generate frontend client packages:

stellar scaffold build [options]

Options:

• --build-clients: Deploy contracts and generate TypeScript client packages for them, as configured in scaffold.yml
• --network <name>: Network from scaffold.yml to build for. Defaults to STELLAR_NETWORK, then the network set with stellar network use, then local
• --list or --ls: List package names in order of build
• [Standard Soroban contract build options also supported]

build validates scaffold.yml before compiling and stops if it has errors. Contracts that do not list the selected network are skipped: they are not deployed and not exported from the generated clients index.ts. Clients removed from scaffold.yml are dropped from index.ts on the next build.

Dev Command

Start development mode with hot reloading:

stellar scaffold watch [options]

Options:

• --build-clients: Generate TypeScript client packages while watching
• All options from the build command are also supported, including --network

watch also rebuilds when scaffold.yml changes.

Clean Command

Remove the artifacts Stellar Scaffold generated for a project:

stellar scaffold clean [options]

Options:

• --manifest-path <path>: Path to Cargo.toml (defaults to the current directory)

Clean removes:

• target/stellar/, the deployment state for the local and test networks
• Everything generated into your clients directory, while leaving checked-in files such as .gitkeep alone
• The contract and identity aliases the CLI created for the local and test networks

Reach for it when you want a genuinely fresh deployment. Because Stellar Scaffold only redeploys a contract when the contract itself changes, editing something else — constructor args or after-deploy in scaffold.yml, for instance — will not produce a new instance on its own. Clearing the aliases makes the next stellar scaffold watch deploy from scratch.

Doctor Command

Diagnose environment and configuration problems in a project:

stellar scaffold doctor [options]

Options:

• --env <name>: Environment to diagnose in projects still on environments.toml (defaults to development, or STELLAR_SCAFFOLD_ENV). Ignored for version 2 projects
• --manifest-path <path>: Path to Cargo.toml (defaults to the current directory)
• --json: Emit findings as JSON instead of a report
• --strict: Treat warnings as failures

Doctor runs every check and reports all of them — it does not stop at the first problem. Each finding is one of:

Symbol	Meaning
✅	The check passed
⚠️	Something is likely wrong, but builds can still work
❌	A problem that will break a build or deploy
ℹ️	The check does not apply here

Findings that have a single-command remedy print it on a fix: line beneath.

What it checks

Toolchain — runs anywhere, project or not:

• rustc is installed, and matches rust-toolchain.toml if the project pins a version
• The wasm32v1-none target contracts compile to is installed
• The stellar CLI is installed, and its major version matches the one this release was built against
• Node and the package manager named by project.package-manager in scaffold.yml (or a legacy package.json packageManager field) are installed

Project — needs a Cargo workspace:

• scaffold.yml exists and uses a schema version this CLI supports. For version 2, every problem stellar scaffold config check would report is listed under the scaffold-yml check
• The contracts-dir and clients-dir directories exist
• The running CLI satisfies the project's engines.stellar-scaffold constraint
• .env exists when there is a .env.example to copy from
• For projects still on environments.toml: it parses, defines the selected environment, has a usable network, and names contracts that exist in the workspace
• For projects still on environments.toml: every extension the environment lists can be found and reports a valid manifest

Network — only for projects on environments.toml whose selected environment sets run_locally = true. These checks are skipped for version 2 projects:

• The Docker daemon is running, not merely installed
• The local network's RPC endpoint reports healthy
• Friendbot is responding

Example

$ stellar scaffold doctor
   Toolchain
✅ rustc              1.93.0 (rust-toolchain.toml: 1.93.0)
✅ wasm-target        wasm32v1-none
✅ stellar-cli        27.0.0
✅ node               v24.16.0
✅ package-manager    npm 11.13.0
   Project
✅ scaffold-yml       scaffold.yml schema version 2
✅ contracts-dir      contracts
✅ clients-dir        app-lib/clients
✅ engine-constraint  stellar-scaffold 0.0.27
⚠️ dot-env            .env is missing
    fix: cp .env.example .env
   Network
ℹ️ docker-daemon      no environment configured
ℹ️ localnet           no environment configured
   0 problems, 2 warnings

Exit codes and CI

Doctor exits 1 when any check reports a problem, and 0 otherwise — warnings alone do not fail it. Pass --strict to fail on warnings too.

For CI, combine --json with --strict:

stellar scaffold doctor --json --strict

The JSON holds a checks array — each entry with name, category, severity, message, and fix — plus a summary object tallying each severity.

Config Command

Validate and inspect scaffold.yml:

stellar scaffold config check [options]
stellar scaffold config show [options]

config check validates the whole file and reports every problem at once, each with its line, a code, and a suggested fix. It makes no network calls and reads no keys, so it is safe to run in CI. It exits non-zero on errors.

• --network <name>: Also check that this network is declared under networks: (defaults to STELLAR_NETWORK if set)
• --strict: Treat warnings as failures
• --json: Print diagnostics as JSON ([] when clean)
• --manifest-path <path>: Path to Cargo.toml (defaults to the current directory)

config show prints the fully resolved config for one network, in YAML: extends applied, built-in defaults filled in, per-network contract overrides merged, and ${env.…}/${network.…} substituted. ${account.…} references are left as written.

• --network <name>: Network to resolve (defaults to STELLAR_NETWORK, then local)
• --json: Print JSON instead of YAML
• --manifest-path <path>: Path to Cargo.toml (defaults to the current directory)

$ stellar scaffold config check
✅ scaffold.yml is valid
$ stellar scaffold config show --network testnet

Both commands read only version 2 files.

Update Environment Command

Update environment variables in the .env file:

stellar scaffold update-env --name <var-name> [options]

Options:

• --name: Name of environment variable to update
• --value: New value (if not provided, reads from stdin)
• --env-file: Path to .env file (defaults to ".env")