The Forest Protocol CLI is a command-line tool for interacting with the Forest Protocol ecosystem. It provides commands for managing the network, providers, agreements, validators, agreements and more.
- Installation
- Configuration
- Global Options
- Commands
- Common Options
- Examples
- Error Handling
- Tips
- Support
Install or update the CLI globally via npm:
npm i @forest-protocols/cli@latest -gImportant
By default the CLI comes pre-configured with values as below. If you plan on using it for reading data no action is required. If you plan writing data (registering, entering agreements etc.) then it is required to set the account.
At startup, the Forest CLI creates a default configuration file located at $HOME/.forest/config.json (if it doesn't already exist). The configuration default parameters are listed below:
| Name | Default | Possible Values | Description |
|---|---|---|---|
| pipe | http |
http, xmtp |
Defines which protocol will be used to communicate with the Actors |
| rpcHost | https://base-sepolia-rpc.publicnode.com |
An RPC host without protocol part | Defines the RPC host that will be using to communicate with the blockchain |
| indexerAPI | https://indexer.forestai.io |
URL of the indexer | Defines the endpoint that exposes an API with Forest data access |
| chain | base-sepolia |
anvil, optimism, optimism-sepolia, base, base-sepolia |
Defines which blockchain will be used |
| account | undefined |
Private key of an EOA | Defines what account will be used for blockchain transactions |
| env | production |
dev or production |
Defines which environment is going to be used (e.g for XMTP communication) |
| rateLimit | 10 |
Positive integer | Defines the maximum number of RPC requests allowed per time window |
| rateLimitTimeWindow | 2000 (2 seconds) |
Positive integer (milliseconds) | Defines the time window for RPC rate limiting in milliseconds |
| registryAddress | as per SDK definition | An EVM compatible address | Defines the address of the Forest Registry contract to be used |
| slasherAddress | as per SDK definition | An EVM compatible address | Defines the address of the Forest Slasher contract to be used |
| tokenAddress | as per SDK definition | An EVM compatible address | Defines the address of the Forest Token contract to be used |
| usdcAddress | as per SDK definition | An EVM compatible address | Defines the address of the USDC Token contract to be used |
# View all configuration
forest config get
# View specific configuration
forest config get <config-name>To change configuration values, use the command below:
forest config set <config-name> <config-value>Examples:
# Set RPC host
forest config set rpcHost https://mainnet.infura.io/v3/YOUR-PROJECT-ID
# Set chain
forest config set chain base-sepolia
# Set account private key
forest config set account 0x1234567890abcdef...
# Set environment
forest config set env productionCaution
Security Warning: Never share your private key or commit it to version control. Keep it secure and use environment variables or secure configuration files in production environments.
Tip
If you are planning on interacting with the system beyond reading data, it is advised to set the account so that you don't have to append the private key to all commands that require it.
Tip
Alternatively, if you already have a config file, you can force the CLI to use it (without setting all values individually using the forest config set command), by taking the approach described below.
By default, configurations are stored in $HOME/.forest/config.json. To use a different configuration file, you can set the FOREST_CONFIG environment variable to point to your custom file:
export FOREST_CONFIG=/home/user/forest-configs/john/config.json
forest config get # Uses the configuration file specified aboveImportant
When using a custom configuration file, the CLI will also use the same directory for storing other data (such as API spec files). It's recommended to organize your configuration files in separate directories for better management and to avoid conflicts.
The CLI supports several global options that can be used with any command:
forest [options] <command>-y, --yes- Assumes that all questions will be answered with 'Yes'-s, --short-address- Makes all address outputs shorter--rpc <rpc host>- Uses the given RPC endpoint for blockchain communication, overwrites value set in the config--chain <chain name>- Uses the given blockchain (anvil, optimism-sepolia, optimism, base, base-sepolia), overwrites value set in the config--registry <address>- Uses the given address for Forest Registry smart contract, overwrites value set in the config--token <address>- Uses the given address for Forest Token smart contract, overwrites value set in the config--slasher <address>- Uses the given address for Forest Slasher smart contract, overwrites value set in the config--usdc <address>- Uses the given address for USDC smart contract, overwrites value set in the config
Network commands allow you to manage Forest Network settings and operations.
Alias: net
Updates the Network settings.
forest network set [options]Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config--in-pt-register-fee <amount>- Updates the Actor registration fee in a Protocol--actor-register-fee <amount>- Updates the Actor registration fee in the Network--burn-ratio <percentage>- Updates the burn ratio of FOREST fees that are burned on transfer to Treasury--max-pt <count>- Updates the maximum Protocol count--pt-register-fee <amount>- Updates the Protocol registration fee in the Network--revenue-share <percentage>- Updates the revenue share--treasury <address>- Updates the treasury address
Example:
forest network set --actor-register-fee 100 --burn-ratio 5 --account 0x123...Pauses the Network.
forest network pause -a <private-key>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config
Unpauses the Network.
forest network unpause -a <private-key>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config
Closes the current epoch.
forest network close-epoch -a <private-key>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config
Manages network emissions. The default view shows the split of emissions between Protocols. Use the subcommands (available using options) for more details on emissions within Protocols.
forest network emissions [options]Options:
--protocol <ptAddress>- Show all emissions for protocol owners, providers and validators of a specific protocol--providers- Show all emissions for providers of a specific protocol (requires--protocol)--validators- Show all emissions for validators of a specific protocol (requires--protocol)--pto- Show all emissions for protocol owners of a specific protocol (requires--protocol)--granular-data <actorAddressOrId>- Show granular validation details for a specific actor in a protocol (requires--protocol)--save <output>- Save the emissions to a file as CSV or JSON (if the output is given as .json)
Examples:
- View all protocol emissions (default):
forest network emissions- View emissions for a specific protocol:
forest network emissions --protocol 0x123...- View provider emissions for a specific protocol:
forest network emissions --protocol 0x123... --providers- View validator emissions for a specific protocol:
forest network emissions --protocol 0x123... --validators- View protocol owner emissions for a specific protocol:
forest network emissions --protocol 0x123... --pto- View granular data for a specific actor:
forest network emissions --protocol 0x123... --granular-data 32- Save emissions data to CSV file:
forest network emissions --save emissions.csv- Save emissions data to JSON file:
forest network emissions --protocol 0x123... --providers --save data.jsonGet commands retrieve information about various entities in the Forest Protocol.
Retrieves Network settings and statistics.
forest get networkAlias: net
Retrieves Protocol information.
forest get protocol [addresses...]Aliases: pt, protocols
Arguments:
[addresses...]- Smart contract addresses of the Protocols. If not given shows data for all available Protocols.
Options:
-d, --details- Reads additional details from the Providers/Validators in the Protocols (default: true)-c, --compact- Limits the detail text outputs to 200 characters to save space in the screen
Lists the registered Offers.
forest get offer [addresses...]Aliases: offers, off
Arguments:
[addresses...]- Lists Offers from the given Protocols
Options:
--details- Reads additional details about the Offers from the Providers (default: true)--status <active | inactive | all>- Filters Offers by status (default: "active")-c, --compact- Limits the detail text outputs to 200 characters to save space in the screen
Gets one or more Provider(s) information.
forest get provider [address or id...]Aliases: prov, provs, providers
Arguments:
[address or id...]- Owner wallet address or IDs of the Providers (if not provided, shows all providers)
Gets one or more Validator(s) information.
forest get validator [address or id...]Aliases: val, vals, validators
Arguments:
[address or id...]- Owner wallet address or IDs of the Validators (if not provided, shows all validators)
Gets one or more Protocol Owner(s) information.
forest get pt-owner [address or id...]Aliases: pto, ptos, pt-owners
Arguments:
[address or id...]- Owner wallet address or IDs of the Protocol Owners (if not provided, shows all protocol owners)
Provider commands allow providers to manage their offers and operations.
Alias: prov
Registers an Offer into a Protocol.
forest provider register-offer [options]Required Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address--details <file>- Detailed information about the Offer--fee <amount>- Non-exponent per second price of the offer. 1 unit is approximately 2.60 USDC per month--stock <amount>- Stock amount of the offer
Example:
forest provider register-offer \
-a 0x123... \
-p 0x456... \
--details offer-details.json \
--fee 1000000 \
--stock 10Pauses an active offer.
forest provider pause-offer -a <private-key> -p <protocol-address> -o <offer-id>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address-o, --offer <number>- Offer ID
Unpauses a paused offer.
forest provider unpause-offer -a <private-key> -p <protocol-address> -o <offer-id>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address-o, --offer <number>- Offer ID
Closes an offer.
forest provider close-offer -a <private-key> -p <protocol-address> -o <offer-id>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address-o, --offer <number>- Offer ID
Withdraws funds from an offer.
forest provider withdraw -a <private-key> -p <protocol-address> -o <offer-id>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address-o, --offer <number>- Offer ID
Registers as a provider in a protocol.
forest provider register-in -a <private-key> -p <protocol-address>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address
Updates provider information.
forest provider update -a <private-key> -p <protocol-address>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address
Adds collateral to provider account.
forest provider topup-collateral -a <private-key> -p <protocol-address>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address
Withdraws collateral from provider account.
forest provider withdraw-collateral -a <private-key> -p <protocol-address>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address
Agreement commands allow users to manage their service agreements with providers.
Enters into an Agreement with a Provider in the given Protocol and Offer.
forest agreement enter [options]Required Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address-o, --offer <number>- Offer ID
Optional Options:
--deposit <number>- Amount of USDC for initial deposit (defaults to 2 months of fee)
Example:
forest agreement enter \
-a 0x123... \
-p 0x456... \
-o 1 \
--deposit 100Lists all entered Agreements in the given Protocol.
forest agreement list [options]Alias: ls
Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address-c, --closed- Lists closed agreements
Example:
forest agreement list -a 0x123... -p 0x456...Shows detailed information about a specific agreement.
forest agreement details -a <private-key> -p <protocol-address> -i <agreement-id>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address-i, --agreement-id <number>- Agreement ID
Closes an active agreement.
forest agreement close -a <private-key> -p <protocol-address> -i <agreement-id>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address-i, --agreement-id <number>- Agreement ID
Adds funds to an agreement.
forest agreement topup -a <private-key> -p <protocol-address> -i <agreement-id>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address-i, --agreement-id <number>- Agreement ID
Withdraws funds from an agreement.
forest agreement withdraw -a <private-key> -p <protocol-address> -i <agreement-id>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address-i, --agreement-id <number>- Agreement ID
Wallet commands help you manage and view wallet information.
Shows wallet balances for USDC, ETH, and FOREST tokens.
forest wallet balance [address]Arguments:
[address]- Wallet address (optional, uses account if not provided)
Example:
forest wallet balance 0x123...Shows token allowances for a wallet.
forest wallet allowance [address]Arguments:
[address]- Wallet address (optional, uses account if not provided)
Token commands allow an administrator to manage ForestToken contract.
Pauses token operations.
forest token pause -a <private-key>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config
Unpauses token operations.
forest token unpause -a <private-key>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config
Validator commands allow validators to manage their operations and commitments.
Commits Provider scores for a given Protocol.
forest validator commit [options]Required Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address--scores <JSON or file>- JSON file containing Provider scores
Optional Options:
--validator-address <address>- Address of the Validator (defaults to account address)
Example:
forest validator commit \
-a 0x123... \
-p 0x456... \
--scores scores.jsonReveals committed Provider scores.
forest validator reveal [options]Required Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address--scores <JSON or file>- JSON file containing Provider scores
Registers as a validator in a protocol.
forest validator register-in -a <private-key> -p <protocol-address>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address
Updates validator information.
forest validator update -a <private-key> -p <protocol-address>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address
Adds collateral to validator account.
forest validator topup-collateral -a <private-key> -p <protocol-address>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address
Withdraws collateral from validator account.
forest validator withdraw-collateral -a <private-key> -p <protocol-address>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address
Register commands allow entities to register in the Forest Protocol.
Registers as a provider.
forest register provider -a <private-key>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config
Registers as a validator.
forest register validator -a <private-key>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config
Registers as a protocol owner.
forest register pt-owner -a <private-key>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config
Slasher commands allow the admin to manage the ForestSlasher contract.
Pauses slasher operations.
forest slasher pause -a <private-key>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config
Unpauses slasher operations.
forest slasher unpause -a <private-key>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config
Protocol Token Owner commands allow protocol owners to manage their protocols.
Updates protocol owner information.
forest pt-owner update -a <private-key> -p <protocol-address>Options:
-a, --account <file or private key>- Private key of the caller's wallet, if you omit this option, the private key is taken from config-p, --protocol <address>- Protocol address
API commands provide programmatic access to Forest Protocol data.
Imports data via the API.
forest api import [options]Pipe commands handle communication channels. Use it to send queries to Providers and Validators.
Manages communication pipes.
forest pipe [options]Many commands share common options:
-a, --account <file or private key>- Private key of the caller's wallet-p, --protocol <address>- Protocol address-o, --offer <number>- Offer ID-i, --agreement-id <number>- Agreement ID-P, --pipe <type>- Pipe type (xmtp or http)-E, --endpoint <base url>- Operator endpoint for HTTP Pipe
Warning
The protocol and provider addresses here are for Base Sepolia testnet deployment as of 01.08.2025. These addresses may change over time. Check for up-to-date ones if these do not work.
Follow this step-by-step workflow to get started with the Forest Protocol:
- Install the latest CLI:
npm i @forest-protocols/cli@latest -g- Set up your account:
forest config set account 0x69...368b- See available Protocols with details:
forest get protocol- See latest emissions to Protocols:
forest network emissions- See latest emissions within the Football Predictions Protocol:
forest network emissions --protocol 0x2c21f0c457088814a3696cd7b238cb18b2e69e73 --providers- Browse offers:
forest get offer 0x2c21f0c457088814a3696cd7b238cb18b2e69e73- Enter an agreement with the top Provider from Football Predictions:
forest agreement enter -o 0 -p 0x2c21f0c457088814a3696cd7b238cb18b2e69e73- Import OpenAPI specs for this Protocol to be able to use it from the CLI:
forest api import 0x7e04F0a076E6c8986A7e083e2a215ea1Ac003385- Make a prediction using your purchased service:
# Update the query to use your agreement id from step 7 output
# NOTE: Unix-based syntax - Windows users may need to adjust the --body.challenges object
forest api football-scores predict-fixture-results \
--operator 0x7e04F0a076E6c8986A7e083e2a215ea1Ac003385 \
--provider-id 35 \
--body.id 4361 \
--body.pt 0x2c21f0c457088814a3696cd7b238cb18b2e69e73 \
--body.challenges '[{"challengeId":"21f04f95-6520-4b55-a82a-b7a7416d32f1","homeTeam":"Botafogo","awayTeam":"Cruzeiro","venue":"Estádio Nilton Santos","league":"Serie A","fixtureId":19387075,"kickoffTime":"2025-08-03T19:00:00Z","challengePhaseMinutes":2160,"targetMarket":"1X2","phaseIdentifier":"T36H","difficulty":0.980588461890651}]'Warning
The protocol and provider addresses here are for Base Sepolia testnet deployment as of 01.08.2025. These addresses may change over time. Check for up-to-date ones if these do not work.
Follow these steps to get an AI chat service agreement and use it:
- Enter an agreement with a Provider from Generic LLM:
forest agreement enter -o 3 -p 0x2cf3a88a17fa5c5601de77b44f19a02e572c03af- Import OpenAPI specs for this Protocol:
forest api import 0x683cfa58c67b0699e5885dd6b148f2d5a1801f57- Make a chat completion request:
# Update the query to use your agreement id from step 1 output
# NOTE: Unix-based syntax - Windows users may need to adjust the --body.messages object
forest api gllm chat/completions \
--provider-id 8 \
--body.id <agreement_id_here> \
--body.pt 0x2cf3a88a17fa5c5601de77b44f19a02e572c03af \
--operator 0x683cfa58c67b0699e5885dd6b148f2d5a1801f57 \
--body.messages '[{"role": "user", "content": "Hello, how are you?"}]'Warning
The protocol and provider addresses here are for Base Sepolia testnet deployment as of 01.08.2025. These addresses may change over time. Check for up-to-date ones if these do not work.
Follow these steps to get an AI image generation service agreement and use it:
- Enter an agreement with a Provider from Imagify:
forest agreement enter -o 1 -p 0x8ad79320ccf0e6420ffd4371035590e48a99ed94- Import OpenAPI specs for this Protocol:
forest api import 0x6afc73ddd03157b4bccdd5fb3cb3b48ed31ee977- Generate an image using your purchased service:
# Update the query to use your agreement id from step 1 output
# NOTE: Unix-based syntax - Windows users may need to adjust the --body object
forest api text-to-image generate \
--provider-id 15 \
--body.id <agreement_id_here> \
--body.pt 0x8ad79320ccf0e6420ffd4371035590e48a99ed94 \
--operator 0x6afc73ddd03157b4bccdd5fb3cb3b48ed31ee977 \
--body.prompt "A dog ontop of Empire State Building waiting for love"Important
Always check your wallet balance before starting any provider workflow to ensure you have sufficient funds for registration fees and collateral.
- Check your wallet balance:
forest wallet balance 0x123...- Register as a provider:
forest register provider -a 0x123...- Register in a protocol:
forest provider register-in -a 0x123... -p 0x456...- Create an offer:
forest provider register-offer \
-a 0x123... \
-p 0x456... \
--details my-offer.json \
--fee 1000000 \
--stock 10- Enter an agreement:
forest agreement enter \
-a 0x789... \
-p 0x456... \
-o 1- List your agreements:
forest agreement list -a 0x789... -p 0x456...- Register as a validator:
forest register validator -a 0x123...- Register in a protocol:
forest validator register-in -a 0x123... -p 0x456...- Commit scores:
forest validator commit \
-a 0x123... \
-p 0x456... \
--scores scores.json- Agreement IDs: Each
forest agreement entercommand will output an agreement ID that you need to use in subsequent API calls - Windows Users: You may need to adjust JSON objects in
--bodyparameters to work with Windows command line syntax - Provider IDs: Each protocol has different provider IDs - check the offers to see available providers
The CLI provides detailed error messages and validation. Common error scenarios:
- Invalid private key: Ensure your private key is correct and properly formatted
- Insufficient funds: Check your wallet balance before making transactions
- Network issues: Verify your RPC endpoint and network connection
- Permission errors: Ensure you have the correct permissions for the operation
- Use the
-yflag to skip confirmation prompts in automated scripts - Use the
-sflag for shorter address outputs in logs - Set up configuration to avoid repeating common options
- Use ENS names instead of addresses where possible for better readability
- Check help for any command with
--helpflag - Keep your CLI updated with
npm i @forest-protocols/cli@latest -g
For additional support and documentation, visit the Forest Protocol documentation link or contact the development team on Discord.