CLI Reference

The CodeLayers CLI is the command-line tool that runs on your development machine. It parses your code, builds the dependency graph, encrypts everything, and syncs to the backend where your devices receive updates in real-time.

Installation

curl -fsSL https://codelayers.ai/install.sh | bash

Or with Homebrew:

brew install codelayers-ai/tap/codelayers

Verify installation:

codelayers --version

Global Options

These options work with any command:

Commands

login

Authenticate by entering your 12-word mnemonic phrase.

codelayers login

What happens:

1. You'll be prompted to enter your 12-word mnemonic (generated in the app)
2. Your mnemonic is used to derive an encryption key (never sent to servers)
3. A "sync ID" is derived and sent to the backend to link your devices

Example:

# Enter your mnemonic from the app
codelayers login

# Force new login (e.g., to switch accounts)
codelayers login --force

logout

Sign out and clear stored credentials.

codelayers logout

What happens:

• Clears stored mnemonic and authentication tokens
• Stops any running watch processes
• Does NOT delete your synced data from the backend (it's encrypted and useless without your mnemonic)

status

Show current authentication and sync status.

codelayers status

Example output:

Authentication:
  ✓ Logged in as user_abc123
  ✓ Mnemonic configured (sync ID: a1b2c3...)

Synced Repositories:
  ~/projects/my-app     (last sync: 2 minutes ago)
  ~/projects/api-server (watching)

Backend Connection:
  ✓ WebSocket connected
  2 devices subscribed

explore

Explore any public GitHub Pull Request in 3D — no clone, no checkout, no account required. Opens directly in your browser.

codelayers explore <PR_URL>

What happens:

1. Fetches the PR metadata and diff from GitHub
2. Builds a dependency graph of the repository
3. Calculates blast radius from the PR's changed files
4. Opens an interactive 3D visualization in your browser

Free tier: 10 explores every 30 days. No account required.

Example:

# Explore a PR
codelayers explore https://github.com/openclaw/openclaw/pull/17092

# Works with any public GitHub PR
codelayers explore https://github.com/facebook/react/pull/31763

sync

One-time sync of a repository to the backend.

codelayers sync [PATH]

What happens:

1. Parses all supported files using tree-sitter
2. Builds a dependency graph (functions, classes, imports, calls)
3. Calculates metrics (PageRank, centrality, topological depth)
4. Encrypts the graph with your mnemonic-derived key
5. Uploads encrypted chunks to the backend

Example:

# Sync current directory
codelayers sync

# Sync specific path
codelayers sync ~/projects/my-app

# Force complete re-sync (useful if graph seems corrupted)
codelayers sync --clean

watch

Watch a repository for changes and sync updates to your devices in real-time via the backend.

codelayers watch [PATH] [OPTIONS]

What happens:

1. Does an initial sync (like codelayers sync)
2. Establishes WebSocket connection to backend
3. Watches for file changes and syncs updates in real-time
4. Backend relays updates to connected devices
5. If --agent is specified, launches the AI coding agent

Example:

# Basic watch mode
codelayers watch

# Watch with Claude Code integration
codelayers watch --agent claude

# Watch specific directory with Gemini
codelayers watch ~/projects/api --agent gemini

See AI Agents guide for tips on using the --agent option effectively.

share

Create a shareable link to an interactive 3D code visualization. The link is zero-knowledge encrypted — the server never sees your code.

codelayers share [PATH] [OPTIONS]

Example:

# Share current directory (uncommitted changes as blast radius)
codelayers share

# PR mode: compare base to head
codelayers share . --base origin/main --head HEAD

# Customize expiry
codelayers share --expires 30

# Machine-readable output (for CI/CD)
codelayers share --format json

# Link to a GitHub PR (adds PR title + link in viewer)
codelayers share . --base origin/main --head HEAD \
  --github-repo owner/repo \
  --github-pr 42 \
  --github-pr-title "Add auth flow"

JSON output (when --format json):

{
  "share_url": "https://app.codelayers.ai/s/{uuid}#k={base64_key}",
  "share_id": "uuid",
  "node_count": 1247,
  "file_count": 582,
  "edge_count": 3891,
  "changed_file_count": 12,
  "total_loc": 45230,
  "blast_radius_count": 47,
  "languages": { "rust": 312, "typescript": 156, "swift": 89 }
}

See Web Sharing for details on how encryption works and viewer features.

shares

Manage your shared visualization links.

codelayers shares <SUBCOMMAND>

Example:

# List all shares
codelayers shares list

# List shares for a specific repo
codelayers shares list ~/projects/my-app

# Copy a share URL to clipboard
codelayers shares copy abc-123-def

# Delete a share
codelayers shares remove abc-123-def

# Clean up expired shares
codelayers shares cleanup

api-keys

Create and manage API keys for headless/CI authentication. API keys let you use the CLI in environments where interactive login isn't possible, like GitHub Actions or CI/CD pipelines.

codelayers api-keys <SUBCOMMAND>

Create options:

Example:

# Create a key with default scopes
codelayers api-keys create "GitHub CI"

# Create with specific scopes
codelayers api-keys create "Read Only" --scopes share:read,sync:read

# Create with expiry
codelayers api-keys create "Temp Key" --expires 30

# List all keys
codelayers api-keys list

# Revoke a key
codelayers api-keys revoke key_abc123

Using an API key:

Set the CODELAYERS_API_KEY environment variable:

export CODELAYERS_API_KEY=cl_key_xxxxxxxxxxxx
codelayers share .

When an API key is set, the CLI skips interactive login and uses the key for all API calls.

Requirements: To create API keys, you need the CLI installed, an active Pro subscription, and to be logged in.

pair

Pair with a device using a 6-digit code to share your mnemonic.

codelayers pair

What happens:

1. Generates a 6-digit pairing code
2. Discovers your device via mDNS on local network
3. Waits for the device to enter the code
4. Securely transfers mnemonic to the device

When to use:

• Initial device setup when mnemonic is on CLI
• Sharing mnemonic with a new device
• When you want to pair without manually typing 12 words

Note: After pairing, all data sync happens through the backend WebSocket—P2P is only used for this initial pairing process.

list

List all synced repositories.

codelayers list

Example output:

Synced Repositories:

  ~/projects/my-app
    Last sync: 2024-01-15 10:30:45
    Files: 847
    Graph: 1,523 nodes, 4,291 edges

  ~/projects/api-server
    Last sync: 2024-01-15 10:28:12
    Files: 234
    Graph: 512 nodes, 1,203 edges
    Currently watching

info

Show detailed sync status for a repository.

codelayers info [PATH]

Example output:

Repository: ~/projects/my-app

Sync Status:
  Last sync: 2024-01-15 10:30:45
  Graph version: 47
  Files parsed: 847
  Nodes: 1,523
  Edges: 4,291

Languages Detected:
  TypeScript: 612 files
  Python: 198 files
  JSON: 37 files

Cache:
  Location: ~/.codelayers/
  Size: 12.4 MB

AI Agents

CodeLayers integrates with AI coding assistants to provide spatial context for code conversations.

Supported Agents

How It Works

Interactive Mode (default):

1. Run codelayers watch --agent claude
2. CLI spawns Claude Code as a subprocess
3. You type prompts in the terminal
4. Your device observes the conversation and highlights relevant files

Remote Mode:

1. Your device sends prompts to CLI via WebSocket
2. CLI forwards prompts to the AI agent
3. Responses stream back to your device

Example Session

$ codelayers watch --agent claude

✓ Synced 847 files
✓ Backend WebSocket connected
✓ Claude Code connected

You: How does authentication work in this project?

Claude: Looking at the codebase, authentication is handled in
`src/auth/`. The main entry point is `auth.ts` which uses JWT
tokens stored in cookies...

[CodeLayers highlights: src/auth/auth.ts, src/auth/jwt.ts, src/middleware/auth.ts]

MCP Tools

When using --agent claude, an MCP server provides tools for visualization control:

Supported Languages

CodeLayers uses tree-sitter for parsing. Currently supported:

Files with other extensions are tracked but not parsed for dependencies.