Contract interaction
Clarinet provides powerful tools for interacting with your contracts during development. The console gives you an interactive REPL environment where you can call functions, check state, and debug issues in real-time.
Starting the console
The clarinet console command launches an interactive session with all your contracts deployed to a local simulated blockchain:
$clarinet consoleclarity-repl v2.16.0Enter ".help" for usage hints.Connected to a transient in-memory database.
Once in the console, you have access to a Clarity REPL with your project's contracts already deployed and ready to interact with. The console supports several powerful options for different development scenarios:
| Option | Description |
|---|---|
--enable-remote-data | Connect to mainnet/testnet to query real contracts |
--remote-data-api-url <URL> | Use custom Stacks API endpoint |
--remote-data-initial-height <N> | Set starting block height for remote data |
--deployment-plan-path <PATH> | Use specific deployment plan |
--manifest-path <PATH> | Use alternate Clarinet.toml location |
--enable-clarity-wasm | Enable Clarity Wasm preview (beta) |
Working with remote data
One of the most powerful features is the ability to interact with real mainnet or testnet contracts from your local console. This lets you test against actual deployed contracts:
$clarinet console --enable-remote-data
Now you can interact with mainnet contracts directly:
$(contract-call? 'SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token get-decimals)$(contract-call? 'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.arkadiko-token get-name)
This is invaluable for:
- Testing integrations with existing protocols
- Verifying contract behavior against mainnet state
- Developing contracts that depend on mainnet contracts
Before using remote data, make sure you add the remote contract to your Clarinet.toml file with clarinet requirements add SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token.
Using the Hiro API key
To avoid rate limits when using remote data, set the HIRO_API_KEY environment variable. Clarinet automatically includes this key in all API requests:
$export HIRO_API_KEY=your_api_key_here$clarinet console --enable-remote-data
The API key is sent as the x-api-key header in all requests to Hiro's APIs. You can obtain a free API key from the Hiro Platform.
Working with contracts
The ::get_contracts command lists all available contracts:
$::get_contracts$(contract-call? .counter count-up)$(contract-call? .counter get-count tx-sender)
Working with different principals
The console provides several test wallets you can use. Switch between them to test multi-user scenarios:
$::get_assets_maps$::set_tx_sender ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5
Working with block heights
Test "time-dependent" logic by advancing the chain:
$::get_block_height$::advance_chain_tip 100$::get_block_height
For a complete list of available console commands and their usage, view the CLI reference.