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
PreviousContract DeploymentNextFAQ

Last updated

Was this helpful?