# 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>
```

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

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

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

```bash
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]
```

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

```bash
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]
```

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

```bash
$ clarinet deployments check
✔ Deployment files are valid
```

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

Usage with `generate`

```
clarinet deployments generate [OPTIONS]
```

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

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

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

```bash
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>
```

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

```bash
export CLARINET_MANIFEST_PATH=/path/to/project
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stacks.co/reference/clarinet/cli-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.