CLI Reference

The Runar CLI is the primary interface for creating projects, compiling contracts, running tests, and deploying to the BSV network. This page documents every available command and flag. The CLI is distributed as the runar-cli npm package and invoked with the runar command.

Global Options

runar [command] [options]

Flag	Description
`--version`, `-v`	Print the Runar CLI version
`--help`, `-h`	Show help for the command

runar init

Scaffold a new Runar project.

runar init [name]

Arguments

Argument	Description
`name`	Name of the project directory to create (optional, default: `my-runar-project`)

Example

runar init my-project

Generated Structure

my-project/
  src/
    contracts/           # Contract source files
      P2PKH.runar.ts
  tests/               # Test files
    P2PKH.test.ts
  artifacts/           # Compiled output (gitignored)
  package.json
  tsconfig.json
  .gitignore

runar compile

Compile one or more Runar contracts to Bitcoin Script artifacts.

runar compile <source...> [options]

Arguments

Argument	Description
`source`	One or more contract source files or a glob pattern

Options

Flag	Default	Description
`--output <dir>`	`./artifacts`	Output directory for compiled artifacts
`--ir`	`false`	Include ANF intermediate representation in the artifact
`--asm`	`false`	Include human-readable ASM in the artifact
`--disable-constant-folding`	`false`	Disable the constant folding optimization pass

Examples

# Compile a single contract
runar compile contracts/P2PKH.runar.ts

# Compile all contracts in a directory
runar compile contracts/*.runar.ts --output ./artifacts

# Compile with IR and ASM output
runar compile contracts/PriceBet.runar.ts --asm --ir

Output

For each source file, the compiler produces a JSON artifact:

artifacts/
  P2PKH.json
  PriceBet.json

The artifact format is documented in Output Artifacts.

Exit Codes

Code	Meaning
`0`	Compilation succeeded
`1`	Compilation failed (errors in source)
`2`	Configuration or file system error

runar test

Run the test suite. Delegates to vitest under the hood.

runar test [pattern]

Arguments

Argument	Description
`pattern`	Optional pattern to filter which tests to run

Examples

# Run all tests
runar test

# Run tests matching a pattern
runar test PriceBet

The test runner uses vitest. Additional vitest flags can be passed through your vitest.config.ts or package.json scripts. See The Test Runner for details on the testing framework.

runar debug

Launch an interactive step-through script debugger for a compiled contract artifact.

runar debug <artifact> [options]

Arguments

Argument	Description
`artifact`	Path to a compiled JSON artifact (must include `sourceMap`)

Options

Flag	Default	Description
`-m, --method <name>`		Public method to invoke
`-a, --args <json>`		Method arguments as a JSON object
`-u, --unlock <hex>`		Raw unlocking script hex (alternative to `--method`/`--args`)
`-b, --break <loc>`		Initial breakpoint: opcode index or `file:line`

Example

runar debug ./artifacts/PriceBet.json --method settle --args '{"price": 60000}'

See Debugging Compiled Script for full usage details.

runar deploy

Deploy a compiled contract to the BSV network.

runar deploy <artifact> [options]

Arguments

Argument	Description
`artifact`	Path to the compiled JSON artifact

Options

Flag	Default	Description
`--network <net>`	required	Target network: `mainnet` or `testnet`
`--key <wif>`	required	WIF-encoded private key for funding
`--satoshis <n>`	`10000`	Satoshis to lock in the contract output

Examples

# Deploy to testnet
runar deploy ./artifacts/P2PKH.json \
  --network testnet \
  --key cN1r3... \
  --satoshis 10000

Output

Contract deployed successfully.
  Network:  testnet
  TxID:     a1b2c3d4e5f6...
  Output:   0
  Satoshis: 10000
  Script:   76a914...88ac

Security Notes

Avoid passing mainnet private keys as CLI arguments in shared environments (the key appears in shell history).

runar verify

Verify that an on-chain contract matches a compiled artifact.

runar verify <txid> [options]

Arguments

Argument	Description
`txid`	Transaction ID of the deployed contract

Options

Flag	Default	Description
`--artifact <path>`	required	Path to the compiled artifact to compare against
`--network <net>`	required	Network to query: `mainnet` or `testnet`

Examples

# Verify a deployment
runar verify a1b2c3d4e5f6... \
  --artifact ./artifacts/P2PKH.json \
  --network testnet

Output

Verification passed.
  Contract:     P2PKH
  TxID:         a1b2c3d4e5f6...
  Output:       0
  Script match: yes
  Confirmations: 3

runar codegen

Generate typed bindings from a compiled artifact.

runar codegen <artifact...> [options]

Arguments

Argument	Description
`artifact`	One or more compiled JSON artifacts

Options

Flag	Default	Description
`--output <dir>`, `-o`	`./types`	Output directory for generated files
`-l, --lang <lang>`	`ts`	Target language: `ts`, `go`, `rust`, `python`

Examples

# Generate TypeScript types
runar codegen ./artifacts/P2PKH.json --output ./types

# Generate types for all artifacts
runar codegen ./artifacts/*.json

# Generate Go bindings
runar codegen ./artifacts/Token.json --lang go --output ./bindings

Generated Output

For a P2PKH contract, runar codegen produces:

// types/P2PKH.ts
import { RunarContract, Sig, PubKey, Ripemd160 } from 'runar-sdk';

export interface P2PKHConstructorArgs {
  pubKeyHash: Ripemd160;
}

export interface P2PKHMethods {
  unlock(args: { sig: Sig; pubKey: PubKey }): Promise<CallResult>;
}

export type P2PKHContract = RunarContract & P2PKHMethods;

This gives you full IDE autocompletion and type checking when interacting with contracts through the SDK.