Development

Contributor-facing reference for apps/cli itself. If you only want to use the CLI, start at Commands.

Structure

apps/cli/
├── index.ts              # CLI entry point
├── commands/
│   ├── branch/           # Git branch naming
│   │   ├── index.ts
│   │   ├── create-branch.ts
│   │   └── lib/branch-name-sanitizer.ts
│   ├── read/              # Direct (sync) source reads
│   │   ├── index.ts
│   │   ├── read-gmail-command.ts
│   │   └── lib/gmail-reader.ts
│   ├── ingest/             # Async workflow-based ingestion
│   │   ├── index.ts
│   │   └── ingest-gmail-command.ts
│   ├── worktree/           # Git worktree management
│   │   ├── index.ts
│   │   ├── create-worktree.ts
│   │   ├── list-worktree.ts
│   │   ├── remove-worktree.ts
│   │   ├── pr/             # GitHub PR commands
│   │   │   ├── index.ts
│   │   │   ├── pr-list.ts
│   │   │   ├── pr-create.ts
│   │   │   ├── pr-checkout.ts
│   │   │   ├── pr-status.ts
│   │   │   └── pr-sync.ts
│   │   └── lib/             # Worktree utilities
│   │       ├── types.ts
│   │       ├── git-worktree.ts
│   │       ├── github-pr.ts
│   │       ├── worktree-setup.ts
│   │       ├── port-calculator.ts
│   │       └── term-launcher.ts
│   ├── scrape/             # Chrome-CDP site scraping
│   │   └── index.ts
│   ├── tasks/              # Scheduled jobs on a deployed target
│   │   └── index.ts
│   └── agent/              # Run coding cards from the board
│       ├── index.ts
│       ├── config.ts
│       ├── runner.ts
│       └── normalize.ts
├── lib/                    # Shared utilities (auth, CLI context, env)
│   ├── AuthManager.ts
│   ├── cli-context.ts
│   └── env.ts
├── tests/                  # Integration tests
└── data/                   # Local data storage

Dependencies

• @viite-ai/platform-sdk - Platform SDK for API communication
• @viite-ai/platform-domain - Domain entities
• @viite-ai/platform-utils - Shared utilities
• cleye - CLI framework
• @clack/prompts - Interactive prompts
• puppeteer-core - Chrome CDP client (used by scrape)

Working on the CLI

Prerequisites

1. Start the API server:

   bun run api

2. Create a test user via the dashboard at http://localhost:5000

Adding New Commands

1. Create a command file under apps/cli/commands/
2. Import and add it to commands in apps/cli/index.ts (or the parent command’s index.ts for a subcommand)
3. Use createCliContext() for API access:

import { createCliContext } from '../../lib/cli-context.js';

const ctx = await createCliContext();
const result = await ctx.apiClient.someService.someMethod(...);

createCliContext() handles login/session resolution and returns { logger, apiClient, config, baseUrl, userId, email }.

Building

# Build from root
bun run build

# Or build the CLI independently
cd apps/cli
bun run build          # ESM bundle for npm (viite-cli)
bun run compile         # standalone binary for the current platform
bun run compile:all     # standalone binaries for macOS/Linux/Windows

Troubleshooting

“Cannot find module ‘@viite-ai/platform-sdk’”

Build the workspace packages:

bun run build

“Authentication failed” or 401 Unauthorized

1. Check the API server is running on http://localhost:3000
2. Verify the user exists with correct credentials
3. Renew the session: bun run api:renew-session your@email.com password
4. Or clear the session file: rm ~/.platform-cli/session.json

Testing

Integration tests (require the API server running):

bun test ./apps/cli/tests/integration/gmail-source.test.ts

Unit tests (run as part of the root test:unit script):

bun test ./apps/cli/commands/agent ./apps/cli/lib