Canton application development CLI — project scaffolding, DAML compilation, testing, local sandbox management, and MCP server for AI-assisted development.

• Single binary, zero runtime dependencies for core commands. Download one file, chmod +x, run. The core CLI (scaffolding, MCP server, environments, plugins) requires no JVM, Node.js, or container runtime.
• Cross-compilation. GOOS=linux GOARCH=amd64 go build produces a Linux binary from macOS. CI builds for all platforms trivially.
• Static linking. No shared library conflicts, no version mismatches, no container image bloat. Copy the binary into an air-gapped environment and it works.
• Plugin system. Extensible via JSON-RPC plugins. Core commands prove the plugin contract before any external plugins ship.

# Homebrew (macOS)
brew install displacetech/tap/cantool

# Binary download (preferred for institutions)
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m); [ "$ARCH" = "x86_64" ] && ARCH="amd64"
curl -sSL "https://github.com/DisplaceTech/Cantool/releases/latest/download/cantool_${OS}_${ARCH}.tar.gz" \
  | tar xz cantool
sudo mv cantool /usr/local/bin/

# Go install (for Go developers)
go install github.com/displacetech/cantool@latest

# Create a new project
cantool init my-app --template basic
cd my-app

# Check environment status
cantool status

# Manage environments
cantool env add local --host localhost --ledger-port 5011
cantool env use local

# See installed plugins
cantool plugin list

To also get build, test, dev, clean, and doctor commands, enable the convenience plugin (see Plugins).

These commands are provided by the built-in convenience plugin and must be enabled in cantool.yaml (see Plugins). They delegate to dpm/daml and print an attribution line to stderr (e.g., -> delegating to dpm build).

Cantool supports two levels of configuration:

1. Global config — checked in order: $XDG_CONFIG_HOME/cantool/config.yaml (default ~/.config/cantool/), ~/Library/Application Support/cantool/config.yaml (macOS only), ~/.cantool/config.yaml (fallback). Applied to all projects. Useful for enabling plugins once across all projects.
2. Project config — cantool.yaml in the project root. Project settings override global settings.

Create a global config to set defaults for all projects:

# Linux
mkdir -p ~/.config/cantool
cat > ~/.config/cantool/config.yaml << 'EOF'
version: "1"
plugins:
  convenience:
    enabled: true
EOF

# macOS
mkdir -p ~/Library/Application\ Support/cantool
cat > ~/Library/Application\ Support/cantool/config.yaml << 'EOF'
version: "1"
plugins:
  convenience:
    enabled: true
EOF

This enables convenience commands everywhere without editing each project's cantool.yaml. A project can still override the global setting by explicitly setting plugins.convenience.enabled: false in its own cantool.yaml.

Cantool projects use a cantool.yaml file:

version: "1"

project:
  name: my-app
  sdk-version: "3.4.11"

parties:
  - name: Alice
    display: "Alice Corp"
  - name: Bob
    display: "Bob Trading"

environments:
  local:
    host: localhost
    ledger-port: 5011
    json-api-port: 7575

dev:
  watch-paths:
    - "daml/"
  hot-reload: true
  sandbox-port: 5011

plugins:
  convenience:
    enabled: true

Configure Cantool as an MCP server for Claude Code, Cursor, or other MCP-aware tools:

{
  "mcpServers": {
    "cantool": {
      "command": "cantool",
      "args": ["mcp", "serve"]
    }
  }
}

Available tools: query_contracts, list_parties, ledger_status, allocate_party, upload_dar, list_packages

Available resources: canton://contracts, canton://parties, canton://packages

Cantool supports built-in and external plugins. Plugins are configured in the plugins section of cantool.yaml or the global config file (see Configuration).

The convenience plugin ships with Cantool and provides wrapper commands for common dpm/daml operations. It is disabled by default.

To enable it globally (all projects):

# Linux
mkdir -p ~/.config/cantool
cat > ~/.config/cantool/config.yaml << 'EOF'
version: "1"
plugins:
  convenience:
    enabled: true
EOF

# macOS
mkdir -p ~/Library/Application\ Support/cantool
cat > ~/Library/Application\ Support/cantool/config.yaml << 'EOF'
version: "1"
plugins:
  convenience:
    enabled: true
EOF

Or enable it per-project in cantool.yaml:

plugins:
  convenience:
    enabled: true

To disable it in a specific project (overriding a global enable):

plugins:
  convenience:
    enabled: false

When enabled, the following commands become available:

When a convenience command delegates to an external tool, it prints a single attribution line to stderr (e.g., -> delegating to dpm build).

Use cantool plugin list to see installed plugins.

External plugins are standalone binaries that communicate via JSON-RPC 2.0 over stdin/stdout. Plugins are discovered in ~/.cantool/plugins/ and must respond to --metadata with a JSON payload:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My custom plugin",
  "author": "Your Name",
  "min_host_version": "0.1.0"
}

See internal/plugin/interface.go for the full plugin interface definition.

Cantool uses structured error codes by subsystem:

Every error includes a human-readable suggestion for how to fix it.

Apache 2.0