Skip to main content
Blueprint is a CLI tool for TON smart contract development. This reference covers all available commands, options, configuration, and API methods.

​
CLI commands

Blueprint provides a comprehensive set of CLI commands for smart contract development, testing, and deployment. Commands support both interactive and non-interactive modes.

​
create

npx blueprint create <CONTRACT> --type <TYPE>
Creates a new smart contract with all necessary files including the contract source, TypeScript wrapper, test file, and deployment script.

​
Interactive mode

npx blueprint create
Launches an interactive wizard that guides you through:
  1. Contract name selection (validates CamelCase format)
  2. Programming language choice (Tolk, FunC, or Tact)
  3. Template type selection (empty or counter example)

​
Non-interactive mode

npx blueprint create <CONTRACT> --type <TYPE>
Parameters:
  • <CONTRACT> — contract name in CamelCase format (e.g., MyAwesomeContract)
  • <TYPE> — template type from available options
Available template types:
  • tolk-empty — an empty contract (Tolk)
  • func-empty — an empty contract (FunC)
  • tact-empty — an empty contract (Tact)
  • tolk-counter — a simple counter contract (Tolk)
  • func-counter — a simple counter contract (FunC)
  • tact-counter — a simple counter contract (Tact)
Usage examples: 
# Create empty Tolk contract
npx blueprint create MyToken --type tolk-empty

# Create Tolk counter example
npx blueprint create SimpleCounter --type tolk-counter

# Create contract interactively
npx blueprint create
Generated files:
  • contracts/MyContract.{tolk|fc|tact} — contract source code
  • wrappers/MyContract.ts — TypeScript wrapper for contract interaction
  • tests/MyContract.spec.ts — Jest test suite with basic test cases
  • scripts/deployMyContract.ts — deployment script with network configuration

​
build

npx blueprint build <CONTRACT> --all
Compiles smart contracts using their corresponding .compile.ts configuration files.

​
Interactive mode

npx blueprint build
Displays a list of all available contracts with .compile.ts files for selection. Shows compilation status and allows building individual contracts or all at once.

​
Non-interactive mode

npx blueprint build <CONTRACT>
npx blueprint build --all
Parameters:
  • <CONTRACT> — specific contract name to build (matches the .compile.ts filename)
  • --all — build all contracts in the project that have compilation configurations
Usage examples: 
# Build specific contract
npx blueprint build MyToken

# Build all contracts
npx blueprint build --all

# Interactive selection
npx blueprint build
For detailed information about build artifacts, see Compiled Artifacts.

​
run

npx blueprint run <SCRIPT> <ARGS...> <OPTIONS>
Executes TypeScript scripts from the scripts/ directory with full network provider access. Commonly used for contract deployment, interaction, and maintenance tasks.

​
Interactive mode

npx blueprint run
Displays a list of all available scripts in the scripts/ directory to select from.

​
Non-interactive mode

npx blueprint run <SCRIPT> <ARGS...>
Parameters:
  • <SCRIPT> — script name (without .ts extension)
  • <ARGS...> — optional arguments passed to the script
  • --<NETWORK> — network selection (mainnet, testnet)
  • --<DEPLOY_METHOD> — deployment method (tonconnect, mnemonic)
Network options:
  • --mainnet — use TON Mainnet
  • --testnet — use TON Testnet
  • --custom <URL> — use custom network endpoint
  • --custom-version <VERSION> — API version (v2, v4)
  • --custom-type <TYPE> — network type (custom, mainnet, testnet)
  • --custom-key <KEY> — API key (v2 only)
Deploy options:
  • --tonconnect — use TON Connect for deployment
  • --deeplink — use deep link for deployment
  • --mnemonic — use mnemonic for deployment
Explorer options:
  • --tonscan — use Tonscan explorer
  • --tonviewer — use Tonviewer explorer (default)
  • --toncx — use Toncx explorer
  • --dton — use Dton explorer
Usage examples: 
# Deploy contract to testnet with TON Connect
npx blueprint run deployCounter --testnet --tonconnect

# Deploy to testnet with mnemonic
npx blueprint run deployCounter --testnet --mnemonic

# Run script with custom arguments
npx blueprint run updateConfig arg1 arg2 --testnet

# Use custom network configuration
npx blueprint run deployContract \
  --custom https://toncenter.com/api/v2/jsonRPC \
  --custom-version v2 \
  --custom-type mainnet \
  --custom-key <YOUR_API_KEY>
  • <YOUR_API_KEY> — API key for the selected provider (v2 only).
Requirements:
  • Scripts must be located in scripts/ directory
  • Script files must export a run function:
import { NetworkProvider } from '@ton/blueprint';

export async function run(provider: NetworkProvider, args: string[]) {

}
Environment variables: For mnemonic-based deployments, configure these environment variables.

​
test

Run the full project test suite with all .spec.ts files.

​
Basic usage

npx blueprint test
Run all test files in the tests/ directory.

​
Collecting coverage

npx blueprint test --coverage
Run tests and collect coverage into coverage/ directory.

​
Gas reporting

npx blueprint test --gas-report
# or
npx blueprint test -g
Run tests and compare with the last snapshot’s metrics.

​
Specific test file

npx blueprint test <CONTRACT_NAME>
Examples: 
npx blueprint test
npx blueprint test MyContract
Test file requirements:
  • Test files should be located in tests/ directory
  • Use .spec.ts extension
  • Supports standard Jest syntax and matchers

​
verify

Verify a deployed contract using TON Contract Verifier.

​
Basic usage

npx blueprint verify
Interactive mode to select contract and network.

​
Non-interactive mode

npx blueprint verify <CONTRACT> --network <NETWORK>
Parameters:
  • <CONTRACT> — contract name to verify
  • --network <NETWORK> — network (mainnet, testnet)
  • --compiler-version <VERSION> — compiler version used for building
  • --custom <URL> — custom network endpoint
  • --custom-version <VERSION> — API version (v2 default)
  • --custom-type <TYPE> — network type (mainnet, testnet)
  • --custom-key <KEY> — API key (v2 only)
Examples: 
npx blueprint verify MyContract --network mainnet
npx blueprint verify MyContract --network testnet --compiler-version 0.4.4-newops.1
Custom network verification: 
npx blueprint verify MyContract \
  --custom https://toncenter.com/api/v2/jsonRPC \
  --custom-version v2 \
  --custom-type mainnet \
  --custom-key <YOUR_API_KEY> \
  --compiler-version 0.4.4-newops.1

​
help

Show detailed help. 
npx blueprint help
npx blueprint help <COMMAND>
Examples: 
npx blueprint help
npx blueprint help create
npx blueprint help run

​
set

Sets language versions. 
npx blueprint set <KEY> <VALUE>
Available keys:
  • func — overrides @ton-community/func-js-bin version

​
convert

Converts legacy bash build scripts to Blueprint wrappers. 
npx blueprint convert <PATH_TO_BUILD_SCRIPT>

​
rename

Renames a contract by matching in wrappers, scripts, and tests. 
npx blueprint rename <OLD_NAME> <NEW_NAME>

​
pack

Builds and prepares a publish-ready package of wrappers. 
npx blueprint pack
Flags:
  • --no-warn, -n — ignore warnings about modifying tsconfig.json and package.json, and about removing the dist directory
Output:
  • Creates deployment-ready package
  • Includes compiled artifacts
  • Bundles dependencies

​
snapshot

Creates snapshots with gas usage and cell sizes. 
npx blueprint snapshot
Flags:
  • --label=<COMMENT>, -l=<COMMENT> — add a comment label to the snapshot
Features:
  • Run with gas usage and cell sizes collected
  • Write a new snapshot
  • Useful for regression testing

​
Environment variables

Blueprint supports environment variables for wallet configuration when using mnemonic provider:
  • WALLET_MNEMONIC — wallet mnemonic phrase (space-separated words).
  • WALLET_VERSION — wallet contract version (v1r1, v1r2, v1r3, v2r1, v2r2, v3r1, v3r2, v4r1, v4r2, v4, v5r1).
  • WALLET_ID — wallet ID for versions earlier than v5r1.
  • SUBWALLET_NUMBER — subwallet number for v5r1 wallets.

​
Example .env file

WALLET_MNEMONIC="<MNEMONIC_24_WORDS>"
WALLET_VERSION=v4
WALLET_ID=698983191
SUBWALLET_NUMBER=0
  • <MNEMONIC_24_WORDS> — 24-word wallet mnemonic (space-separated).
⌘I