CLI Reference - Testship Command Line Interface Documentation

Overview

TestShip provides a command-line interface (CLI) for starting and managing the interactive testing server for your Anchor programs.

Installation

Quick Start with npx (Recommended)

Run TestShip directly without installation:

npx @blockchain-hq/testship@latest start

Benefits of npx:

✅ Always uses the latest version
✅ No global installation required
✅ No version management needed
✅ Perfect for CI/CD and temporary usage

Global Installation (Alternative)

Install TestShip globally for repeated use:

npm install -g @blockchain-hq/testship
# or
yarn global add @blockchain-hq/testship
# or
pnpm add -g @blockchain-hq/testship

📦 Package: @blockchain-hq/testship on npm

Commands

`testship start`

Starts the TestShip development server with an interactive UI for testing your Anchor program.

Usage:

testship start [options]

Options:

Option	Alias	Description	Default
`--port <port>`	`-p`	Port number to run the dev server on	`3000`

Examples:

# Using npx (recommended)
npx @blockchain-hq/testship@latest start

# Start on default port (3000) - if installed globally
testship start

# Start on custom port
npx @blockchain-hq/testship@latest start --port 8080
testship start -p 8080  # if installed globally

`testship --version`

Display the current version of TestShip.

testship --version

`testship --help`

Display help information for TestShip commands.

testship --help

How It Works

When you run testship start, the CLI performs the following steps:

Project Detection: Scans the current directory for Anchor.toml to verify it’s an Anchor project
IDL Discovery: Looks for IDL files in target/idl/ directory
Program Selection: If multiple programs are found, prompts you to select one
Server Launch: Starts the development server and opens your browser

Requirements

Project Structure

TestShip expects your Anchor project to have the following structure:

your-anchor-project/
├── Anchor.toml           # Required: Anchor configuration
├── target/
│   ├── idl/
│   │   └── your_program.json   # Required: Program IDL
│   └── deploy/
│       └── your_program.so     # Program binary
├── programs/
└── tests/

Prerequisites

Anchor.toml: Must exist in the project root
Built Program: Run anchor build before starting TestShip
IDL Files: At least one .json IDL file in target/idl/

Multiple Programs

If your Anchor workspace contains multiple programs, TestShip will prompt you to select which program to test:

$ testship start
Scanning for Anchor project...
Found Anchor project
? Found multiple Anchor programs. Select one: (Use arrow keys)
❯ counter_program
  voting_program
  token_swap

Use arrow keys to navigate and press Enter to select.

Environment

TestShip runs a local development server that:

Serves the interactive UI at http://localhost:3000 (or your specified port)
Provides API endpoints for IDL and project information
Automatically opens your default browser to the UI

Error Messages

”No Anchor project found”

Error:

Error: No Anchor project found. Please run from Anchor project directory.

Solution: Navigate to your Anchor project root directory (where Anchor.toml is located).

”No IDL directory found”

Error:

Error: No IDL directory found.

Please run: anchor build

Solution: Build your Anchor program to generate the IDL:

anchor build

“No IDL files found”

Error:

Error: No IDL files found.

Please run: anchor build

Solution: Ensure your program compiles successfully:

anchor build

Port Already in Use

If port 3000 is already in use, specify a different port:

testship start --port 3001

Next Steps

Learn about the Interactive UI
Explore PDA Derivation
Check out Account Suggestions