@topo/cli

CLI tool for syncing product context from Topo to your local project.

Installation

No installation required - run directly with npx:

npx @topo/cli sync

Or install globally:

npm install -g @topo/cli
topo sync

Setup

1. Create an API token in Topo: Project Settings → API Tokens
2. Add the token to your project's .env file:

TOPO_API_TOKEN=topo_xxx

Or set it in your shell environment:

export TOPO_API_TOKEN=topo_xxx

Usage

# Sync product context to default directory (.topo)
npx @topo/cli sync

# Specify output directory
npx @topo/cli sync --output ./my-docs

# Use consolidated format (fewer, larger files)
npx @topo/cli sync --format consolidated

# Pass token directly (alternative to env var)
npx @topo/cli sync --token topo_xxx

Options

| Option | Description | Default | |--------|-------------|---------| | -o, --output <dir> | Output directory | .topo | | -t, --token <token> | API token | TOPO_API_TOKEN env var | | -f, --format <format> | structured or consolidated | structured | | --base-url <url> | API base URL (for development) | https://topo.prosaic.fr |

Output

The CLI creates markdown files in a hidden .topo directory (signaling these are managed files, not for manual editing):

.topo/
├── foundations.md
├── ux.md
└── features/
    └── {area}/{feature}.md

Integration with Claude Code

When using the Topo MCP server, Claude will automatically suggest running this CLI to sync product context. Just run the command Claude provides.

Local Development Installation

To use the CLI from a local clone of the Topo repository (without publishing to npm), you can link it to your project:

Option 1: npm link (recommended)

# In the topo/packages/cli directory, build and create a global link
cd /path/to/topo/packages/cli
npm install
npm run build
npm link

# In your Next.js project, link to the local package
cd /path/to/your-nextjs-project
npm link @topo/cli

# Now you can run the CLI
npx topo sync

To unlink later:

cd /path/to/your-nextjs-project
npm unlink @topo/cli

Option 2: Direct path execution

Run the CLI directly without linking:

# From your project directory
node /path/to/topo/packages/cli/dist/index.js sync

Option 3: Add as a local dependency

In your Next.js project's package.json:

{
  "devDependencies": {
    "@topo/cli": "file:/path/to/topo/packages/cli"
  }
}

Then run:

npm install
npx topo sync

Requirements

• Node.js 18+