CLI reference

The Clarinet CLI provides a comprehensive suite of tools for Clarity smart contract development. From project initialization to deployment, Clarinet streamlines your entire development workflow.

Create a new project: clarinet new
Generate a new smart contract: clarinet contracts new
Validate contract syntax and types: clarinet check
Interactive REPL for testing contracts: clarinet console
Launch a local development network: clarinet devnet start
Manage deployments: clarinet deployments

Initialize a new project

clarinet new

clarinet new creates a new project with all necessary configuration files and directory structure.

Usage

clarinet new [OPTIONS] <NAME>

Terminal

$ clarinet new my-defi-protocol
Create directory my-defi-protocol
Create directory contracts
Create directory settings
Create directory tests
Create file Clarinet.toml
Create file settings/Mainnet.toml
Create file settings/Testnet.toml
Create file settings/Devnet.toml
Create directory .vscode
Create file .vscode/settings.json
Create file .vscode/tasks.json
Create file .gitignore
Create file .gitattributes
Create file package.json
Create file tsconfig.json
Create file vitest.config.js

Option	Description
`--disable-telemetry`	Do not provide developer usage telemetry for this project

Manage your contracts

clarinet contracts

clarinet contracts is a subcommand for working with contracts. It has two subcommands:

Command	Description
`new`	Generate files and settings for a new contract
`rm`	Remove files and settings for a contract

Usage with new

clarinet contracts new <COMMAND> <OPTIONS>

Terminal

$ clarinet contracts new fungible-token
Created file contracts/fungible-token.clar
Created file tests/fungible-token.test.ts
Updated Clarinet.toml

Usage with rm

clarinet contracts rm <COMMAND> <OPTIONS>

Terminal

$ clarinet contracts rm old-token
Removed file contracts/old-token.clar
Removed file tests/old-token.test.ts
Updated Clarinet.toml

Option	Description
`--manifest-path <path>`	Path to Clarinet.toml

Validate your contracts

clarinet check

clarinet check checks contracts syntax and performs type checking.

Usage

$ clarinet check [FILE] [OPTIONS]

Terminal

$ clarinet check
✔ 3 contracts checked
$ clarinet check contracts/token.clar
✔ contracts/token.clar syntax checks passed

Option	Short	Description
`--manifest-path <path>`	`-m`	Path to Clarinet.toml
`--deployment-plan-path <path>`	`-p`	If specified, use this deployment file
`--use-on-disk-deployment-plan`	`-d`	Use on disk deployment plan (prevent updates computing)
`--use-computed-deployment-plan`	`-c`	Use computed deployment plan (will overwrite on disk version if any update)
`--enable-clarity-wasm`		Allow the Clarity Wasm preview to run in parallel with the Clarity interpreter (beta)

Interact with your contracts in a local REPL

clarinet console

clarinet console loads contracts in a REPL for an interactive session.

Usage

$ clarinet console [OPTIONS]

Terminal

$ clarinet console
clarity-repl v1.0.0
Enter ".help" for usage hints.
Connected to a transient in-memory database.

The Clarinet console offers a variety of commands for contract interaction:

::help: Lists all console commands
::functions: Display all the native functions available in Clarity
::keywords: Display all the native keywords available in Clarity
::describe <function> | <keyword>: Display documentation for a given native function or keyword
::toggle_costs: Display cost analysis after every expression
::toggle_timings: Display the execution duration
::mint_stx <principal> <amount>: Mint STX balance for a given principal
::set_tx_sender <principal>: Set tx-sender variable to principal
::get_assets_maps: Get assets maps for active accounts
::get_contracts: Get contracts
::get_block_height: Get current block height
::advance_chain_tip <count>: Simulate mining of <count> blocks
::advance_stacks_chain_tip <count>: Simulate mining of <count> stacks blocks
::advance_burn_chain_tip <count>: Simulate mining of <count> burnchain blocks
::set_epoch <epoch>: Update the current epoch
::get_epoch: Get current epoch
::debug <expr>: Start an interactive debug session executing <expr>
::trace <expr>: Generate an execution trace for <expr>
::get_costs <expr>: Display the cost analysis
::reload: Reload the existing contract(s) in the session
::read <filename>: Read expressions from a file
::encode <expr>: Encode an expression to a Clarity Value bytes representation
::decode <bytes>: Decode a Clarity Value bytes representation

Option	Short	Description
`--manifest-path <path>`	`-m`	Path to Clarinet.toml
`--deployment-plan-path <path>`	`-p`	If specified, use this deployment file
`--use-on-disk-deployment-plan`	`-d`	Use on disk deployment plan (prevent updates computing)
`--use-computed-deployment-plan`	`-c`	Use computed deployment plan (will overwrite on disk version if any update)
`--enable-remote-data`	`-r`	Enable remote data fetching from mainnet or a testnet
`--remote-data-api-url <url>`	`-a`	Set a custom Stacks Blockchain API URL for remote data fetching
`--remote-data-initial-height <height>`	`-b`	Initial remote Stacks block height
`--enable-clarity-wasm`		Allow the Clarity Wasm preview to run in parallel with the Clarity interpreter (beta)

Start a local development network

clarinet devnet

clarinet devnet is a subcommand for working with Devnet. It has two subcommands:

Command	Description
`start`	Start a local Devnet network for interacting with your contracts
`package`	Generate package of all required devnet artifacts

Usage with start

$ clarinet devnet start [OPTIONS]

Terminal

$ clarinet devnet start

Option	Short	Description
`--manifest-path <path>`	`-m`	Path to Clarinet.toml
`--no-dashboard`		Display streams of logs instead of terminal UI dashboard
`--deployment-plan-path <path>`	`-p`	If specified, use this deployment file
`--use-on-disk-deployment-plan`	`-d`	Use on disk deployment plan (prevent updates computing)
`--use-computed-deployment-plan`	`-c`	Use computed deployment plan (will overwrite on disk version if any update)
`--package <path>`		Path to Package.json produced by 'clarinet devnet package'

Usage with package

$ clarinet devnet package [OPTIONS]

Terminal

$ clarinet devnet package --name my-devnet
Packaging devnet artifacts...
Created file my-devnet.json

Option	Short	Description
`--name <name>`	`-n`	Output json file name
`--manifest-path <path>`	`-m`	Path to Clarinet.toml

Manage your deployments

clarinet deployments

clarinet deployments is a subcommand for managing deployments on Devnet/Testnet/Mainnet.

Command	Description
`check`	Check deployments format
`generate`	Generate new deployment
`apply`	Apply deployment

Usage with check

$ clarinet deployments check [OPTIONS]

Terminal

$ clarinet deployments check
✔ Deployment files are valid

Option	Description
`--manifest-path <path>`	Path to Clarinet.toml

Usage with generate

$ clarinet deployments generate [OPTIONS]

Terminal

$ clarinet deployments generate --testnet
Generated deployment plan
Created file deployments/default.testnet-plan.yaml

Option	Description
`--simnet`	Generate a deployment file for simnet environments (console, tests)
`--devnet`	Generate a deployment file for devnet, using settings/Devnet.toml
`--testnet`	Generate a deployment file for testnet, using settings/Testnet.toml
`--mainnet`	Generate a deployment file for mainnet, using settings/Mainnet.toml
`--manifest-path <path>`	Path to Clarinet.toml
`--no-batch`	Generate a deployment file without trying to batch transactions (simnet only)
`--low-cost`	Compute and set cost, using low priority (network connection required)
`--medium-cost`	Compute and set cost, using medium priority (network connection required)
`--high-cost`	Compute and set cost, using high priority (network connection required)
`--manual-cost`	Leave cost estimation manual

Usage with apply

$ clarinet deployments apply [OPTIONS]

Terminal

$ clarinet deployments apply --testnet
Applying deployment to testnet
✔ Broadcasting transaction for token.clar
  Transaction ID: 0x3d4f5...
  Contract: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.token
✔ All contracts deployed successfully

Option	Short	Description
`--devnet`		Apply default deployment settings/default.devnet-plan.toml
`--testnet`		Apply default deployment settings/default.testnet-plan.toml
`--mainnet`		Apply default deployment settings/default.mainnet-plan.toml
`--manifest-path <path>`	`-m`	Path to Clarinet.toml
`--deployment-plan-path <path>`	`-p`	Apply deployment plan specified
`--no-dashboard`		Display streams of logs instead of terminal UI dashboard
`--use-on-disk-deployment-plan`	`-d`	Use on disk deployment plan (prevent updates computing)
`--use-computed-deployment-plan`	`-c`	Use computed deployment plan (will overwrite on disk version if any update)

Interact with Mainnet contracts

clarinet requirements

clarinet requirements is a subcommand for interacting with Mainnet contracts.

Command	Description
`add`	Add a mainnet contract as a dependency to your project

Usage

$ clarinet requirements <COMMAND>

Terminal

$ clarinet requirements add SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait
Added requirement SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait
Updated Clarinet.toml

Option	Description
`--manifest-path <path>`	Path to Clarinet.toml

Editor Integrations

clarinet lsp

clarinet lsp starts the Language Server Protocol service for Clarity, enabling intelligent code completion, error highlighting, and other IDE features in supported editors.

Usage

$ clarinet lsp

Debugging

clarinet dap

clarinet dap starts the Debug Adapter Protocol service, enabling debugging features like breakpoints, step-through execution, and variable inspection in supported editors.

Usage

$ clarinet dap

Format your code

clarinet format

clarinet format formats Clarity code files according to standard conventions.

Usage

$ clarinet format [OPTIONS]

Terminal

$ clarinet format --dry-run
$ clarinet format --file contracts/token.clar --in-place

Option	Short	Description	Required
`--dry-run`		Only echo the result of formatting	Yes
`--in-place`		Replace the contents of a file with the formatted code	Yes
`--manifest-path <path>`	`-m`	Path to Clarinet.toml	No
`--file <file>`	`-f`	If specified, format only this file	No
`--max-line-length <length>`	`-l`	Maximum line length	No
`--indent <size>`	`-i`	Indentation size, e.g. 2	No
`--tabs`	`-t`	Use tabs instead of spaces	No

Utilities

clarinet completions

clarinet completions generates shell completion scripts for your shell.

Usage

$ clarinet completions <SHELL>

Terminal

$ clarinet completions zsh > ~/.zsh/completions/_clarinet
$ source ~/.zshrc

Supported Shells

bash
zsh
fish
powershell
elvish

Option	Short	Description
`--shell <shell>`	`-s`	Specify which shell to generation completions script for

Environment Variables

Clarinet supports environment variables for configuration. All environment variables are prefixed with CLARINET_:

Terminal

$ export CLARINET_MANIFEST_PATH=/path/to/project