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>

$ 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>

$ 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>

$ 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]

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]

$ 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]

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]

$ 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]

$ clarinet deployments check
✔ Deployment files are valid

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

Usage with generate

clarinet deployments generate [OPTIONS]

$ 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]

$ 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>

$ 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]

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

Option	Short	Description	Required
--check		Check if code is formatted without modifying files	No
--dry-run		Only echo the result of formatting	No
--in-place		Replace the contents of a file with the formatted code	No
--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>

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_:

export CLARINET_MANIFEST_PATH=/path/to/project