CLI Commands

Complete reference for stacksdapp commands

CLI Command Reference

Project management

stacksdapp new <name>

Scaffold a new Scaffold Stacks project.

stacksdapp new my-dapp

Creates a complete project structure with contracts and frontend.

stacksdapp init

Adopt an existing Clarinet repository so it matches scaffold-stacks: adds a frontend/ and Node tooling where needed, keeps your contracts, and normalizes the repo layout when Clarinet currently lives at the root.

When: Run from the repository root (where Clarinet lives today).

Example A — Standard Clarinet layout (before)

my-dapp/
├── Clarinet.toml
├── contracts/
│   └── token.clar          # path in TOML: contracts/token.clar
├── settings/
│   └── Devnet.toml
├── tests/
│   └── token.test.ts
├── package.json
├── tsconfig.json
└── vitest.config.ts

cd my-dapp
stacksdapp init

After normalization (typical result):

my-dapp/
├── contracts/
│   ├── Clarinet.toml       # moved from repo root
│   ├── contracts/
│   │   └── token.clar      # moved from contracts/token.clar
│   ├── settings/           # moved from ./settings if no conflict
│   ├── tests/              # moved from ./tests if no conflict
│   ├── package.json        # etc., if missing under contracts/
│   └── ...
├── frontend/               # added from template if it did not exist
│   ├── scripts/
│   │   └── export-abi.mjs
│   └── ...
└── (root Clarinet.toml removed after move)

Path resolution: Entries like path = "contracts/token.clar" in Clarinet.toml still resolve. The file ends up at contracts/contracts/token.clar relative to the repo root, with Clarinet.toml under contracts/.

Existing frontend/: If frontend/ already exists but frontend/scripts/export-abi.mjs is missing, init exits with an error and does not overwrite your frontend. Add that script, or move or rename frontend/ temporarily, then run init again.

Example B — Already scaffold layout (no file moves)

my-dapp/
├── contracts/
│   └── Clarinet.toml
├── frontend/
│   ├── package.json
│   └── scripts/export-abi.mjs
└── ...

cd my-dapp
stacksdapp init

Normalization is skipped; only missing files are filled in, then npm install and stacksdapp generate run.

Example C — Conflict (error)

If both of these exist, init fails with a message to merge or remove one set, then rerun:

• ./settings
• ./contracts/settings

stacksdapp add <name>

Add a new Clarity contract.

stacksdapp add my-contract

Creates contracts/contracts/my-contract.clar and updates configuration.

Templates

# SIP-010 fungible token
stacksdapp add token --template sip010

# SIP-009 NFT
stacksdapp add nft --template sip009

Development

stacksdapp dev

Start development server.

# Testnet (default)
stacksdapp dev --network testnet

# Mainnet
stacksdapp dev --network mainnet

# Local devnet (requires Docker)
stacksdapp dev

stacksdapp generate

Regenerate TypeScript bindings from contracts.

stacksdapp generate

Runs automatically during dev when contracts change.

Testing & validation

stacksdapp test

Run all tests.

stacksdapp test

Runs contract tests (Clarinet SDK) and frontend tests (Vitest).

stacksdapp check

Type-check Clarity contracts.

stacksdapp check

Validates syntax and types without deployment.

Deployment

stacksdapp deploy

Deploy contracts to network.

# Testnet
stacksdapp deploy --network testnet

# Mainnet
stacksdapp deploy --network mainnet

# Devnet
stacksdapp deploy --network devnet

# Deploy a single contract by name
stacksdapp deploy --network testnet --contract counter

# Preview deployment plan without broadcasting
stacksdapp deploy --network testnet --dry-run

Deploy options

• --network <network>: Target network (testnet, mainnet, or devnet)
• --contract <name>: Deploy only one contract from your project
• --dry-run: Generate and print deployment plan, estimated fee, and contract list without broadcasting transactions

Networks

• testnet: Hiro testnet infrastructure
• mainnet: Stacks mainnet
• devnet: Local Docker environment

Maintenance

stacksdapp upgrade

Refresh npm dependencies in frontend/ and contracts/, then run stacksdapp generate again. Does not rewrite your application logic.

Prerequisites: Full scaffold layout, including:

• contracts/Clarinet.toml
• frontend/package.json

cd my-dapp
stacksdapp upgrade

When to use it: After pulling a newer stacksdapp or template, or when generated bindings feel stale and you want a deterministic refresh without rescaffolding.

What to expect: A spinner and install progress for frontend and contracts, then codegen output (same kind of feedback as init for npm).

stacksdapp clean

Remove generated files and devnet state.

stacksdapp clean

stacksdapp --version

Show CLI version.

stacksdapp --version

Init vs upgrade

Command	Use case
stacksdapp init	First time bringing an existing Clarinet project onto scaffold-stacks.
stacksdapp upgrade	Already a scaffold project; refresh dependencies and regenerate TypeScript bindings.

Configuration files

Clarinet.toml

Contract configuration managed by CLI. In the full scaffold layout, this file lives at contracts/Clarinet.toml.

contracts/settings/*.toml

Network-specific settings:

• Devnet.toml: Local development
• Testnet.toml: Testnet deployment
• Mainnet.toml: Mainnet deployment

frontend/.env.local

Auto-managed network configuration.

Auto-generated files

contracts.ts

Type-safe contract call wrappers.

hooks.ts

React hooks for contract interactions.

DebugContracts.tsx

Live debug UI component.

deployments.json

Deployed contract addresses.