Blueprint CLI reference

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 TON.cx 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 the 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 the 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 the 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 the 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 a 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 the 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).