CLI Commands

A comprehensive list of all Clarinet CLI commands and their usage.

Create a New Project

Create a new Clarinet project with the basic directory structure and configuration files:

Terminal
$ 
clarinet new my-project

This will create a project directory with the following directory layout:

Devnet.toml
Mainnet.toml
Testnet.toml
.gitignore
Clarinet.toml
package.json
tsconfig.json
vitest.config.js

The Clarinet.toml file contains configuration for the smart contracts in your project. When you create contracts in your project, Clarinet will automatically add them to this file.

The settings/Devnet.toml file contains configuration for accounts in the Clarinet console, including the seed phrases and initial balances for a set of out-of-the-box wallets that you can use for testing in the devnet environment.

Add a Contract

Add a new contract to your existing project:

Terminal
$ 
clarinet contract new my-contract

This command updates your project's configuration and creates a new contract file and a corresponding test file:

my-contract.clar
my-contract.test.ts
.gitignore
Clarinet.toml
package.json
tsconfig.json
vitest.config.js
[contracts.my-contract]

path = 'contracts/my-contract.clar'

clarity_version = 2

epoch = 2.4
Adding contracts manually

You can also add contracts to your project by adding the files manually. However, you must add the appropriate configuration to Clarinet.toml in order for Clarinet to recognize the contracts.

Check Contracts

Validate the syntax and semantics of your contracts:

Terminal
$ 
clarinet check

$ 
clarinet check path/to/my-contract.clar

This command uses the Clarinet.toml file to locate and analyze all the contracts in the project. If the Clarity code is valid, the command will indicate success with the response below.

Note

The clarinet check command may also report warnings indicating the code is valid.

Start Development Console

Launch the Clarinet console for interactive development:

Terminal
$ 
clarinet console

Debugging

Inside the console, you can use these debugging commands:

Terminal
$ 
::trace (contract-call? .my-contract my-function)

$ 
::debug (contract-call? .my-contract my-function)

$ 
break my-function

Debug navigation commands:

  • step or s - Step into
  • finish or f - Step out
  • next or n - Step over
  • continue or c - Continue execution

Let's take the clarity_counter_ contract as an example:

(define-map Counters principal uint)



(define-read-only (get-count (who principal))

  (default-to u0 (map-get? Counters who))

)



(define-public (count-up)

  (ok (map-set Counters tx-sender (+ (get-count tx-sender) u1)))

)

Trace

The ::trace command expects an expression, so make a contract-call? with our count-up function and see what happens.

Terminal
$ 
::trace (contract-call? .counter count-up)

Breakpoints

You can also set a breakpoint at a specific line to better understand what's happening in your contract.

With ::debug, you can add breakpoints at a specific line of a contract or function to better understand what's happening in your contracts.

(define-map Counters principal uint)



(define-read-only (get-count (who principal))

  (default-to u0 (map-get? Counters who))

)



(define-public (count-up)

  (ok (map-set Counters tx-sender (+ (get-count tx-sender) u1)))

)



(define-public (count-twice)

  (double)

)



(define-private (double)

  (begin

    (unwrap-panic (count-up))

    (count-up)

  )

)
Terminal
$ 
::debug (contract-call? .counter count-twice)

$ 
break count-up
Breakpoint Commands

To step through these breakpoints, you can use one of the following commands:

  • Step-in (step or s): Step into the sub-expressions.
  • Step-out (finish or f): Complete execution of the current expression and return the result to the parent.
  • Step-over (next or n): Continue to completion of the current expression, stepping over sub-expressions.
  • Continue (continue or c): Continue execution until hitting a breakpoint or completing execution.

Using the continue command, the breakpoint you set in the double function will trigger twice due to two count-up calls, which enables you to do variable and map analysis.

Cost Analysis

Analyze execution costs in the console:

Terminal
$ 
::get_costs (contract-call? .my-contract my-function)

$ 
::toggle_costs

Start Local Devnet

Launch a local development network with all required services:

Terminal
$ 
clarinet devnet start

Requires Docker to be running locally. See installing Docker guide for more information.

Deployment

Generate a deployment plan:

Terminal
$ 
clarinet deployments generate --<network>

Supported networks: consoledevnettestnet, consolemainnet_

Deploy contracts:

Terminal
$ 
clarinet deployments apply --<network>

Add Contract Requirements

Add external contract dependencies:

Terminal
$ 
clarinet requirements add <contract-principal>

Example:

Terminal
$ 
clarinet requirements add SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait

Deployment Plan Transactions

Your deployment plans can include various transaction types:

Contract Operations

- contract-publish:

    contract-name: my-contract

    expected-sender: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM

    cost: 5960

    path: contracts/my-contract.clar

    clarity-version: 2



- contract-call:

    contract-id: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.my-contract

    expected-sender: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM

    method: my-function

    parameters: []

    cost: 5960

Asset Transfers

- stx-transfer:

    expected-sender: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM

    recipient: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.my-contract

    mstx-amount: 1000

    memo: '0x01'

    cost: 10000



- btc-transfer:

    expected-sender: mjSrB3wS4xab3kYqFktwBzfTdPg367ZJ2d

    recipient: bcrt1qnxknq3wqtphv7sfwy07m7e4sr6ut9yt6ed99jg

    sats-amount: 100000000

    sats-per-byte: 10

Simnet Operations

- emulated-contract-publish:

    contract-name: my-contract

    emulated-sender: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM

    path: contracts/my-contract.clar

    clarity-version: 2



- emulated-contract-call:

    contract-id: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.my-contract

    emulated-sender: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM

    method: my-function

    parameters: []
Note

For functions that take no arguments or read-only functions, use an empty parameters list: parameters: []

Concepts

Create a new project

On this page

Create a New ProjectAdd a ContractCheck ContractsStart Development ConsoleDebuggingTraceBreakpointsCost AnalysisStart Local DevnetDeploymentAdd Contract RequirementsDeployment Plan TransactionsContract OperationsAsset TransfersSimnet Operations