Interacting with your contracts locally
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
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.
Without an API key, you're limited to 50 requests per minute. With a free Hiro API key, this increases to 500 requests per minute. For intensive development work, consider using --remote-data-api-url to point to your own Stacks API node.
Working with contracts
Let's explore your deployed 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.
Common issues
Next steps
Now that you understand how to interact with and debug your contracts:
- Learn about testing and validation to write automated tests
- Explore deployment options for moving to testnet
- Check the CLI reference for all console options