@caffeineai/cli

The public Caffeine command-line interface for authentication, project management, local development workflows, and headless AI chat.

Development Release

This is a DEV release. It is published under the npm dev dist-tag and is subject to a rapid release cadence. Expect frequent updates while the CLI package settles.

Features

• Device and browser-based login
• Project listing, inspection, creation, cloning, and deletion
• Team workspace list, status, and switch (X-Workspace-Id)
• Local install, build, check, preview, import, export, config, doctor, and update flows
• Interactive and detached chat sessions over the Caffeine AI API
• Browser chat hand-off when you want the web UI

Installation

npm install -g @caffeineai/cli@dev
caffeine --version

Three equivalent command names are installed: caffeine, caf, and cfn.

Quick Start

caffeine auth login            # Sign in
caffeine projects list         # List your Caffeine projects
caffeine projects clone <id>   # Clone one locally
caffeine build                 # Build the current project
caffeine preview               # Upload a draft to Caffeine cloud

Supported Platforms

Native binaries ship for:

• macOS arm64 and x64
• Linux arm64 and x64, glibc and musl
• Windows arm64 and x64

Commands

Run caffeine <command> --help for the full flag list.

Chat Workflow

caffeine chat
caffeine chat --project-id 11111111-1111-4111-8111-111111111111
caffeine chat interactive --project-id 11111111-1111-4111-8111-111111111111
caffeine chat send --detach "Build a weather dashboard"
caffeine chat active
caffeine chat status
caffeine chat watch --project-id 11111111-1111-4111-8111-111111111111
caffeine chat resume --project-id 11111111-1111-4111-8111-111111111111
caffeine chat transcript --project-id 11111111-1111-4111-8111-111111111111
caffeine chat feed --project-id 11111111-1111-4111-8111-111111111111 --timeout 5s
caffeine chat submit-form \
  --project-id 11111111-1111-4111-8111-111111111111 \
  --message-index 42 \
  --form-data '{"appName":"Habit Hero"}'
caffeine chat open

All commands support --json for machine-readable output.

caffeine chat is the primary human workflow. It resumes likely active chat sessions for the target project, shows a recent transcript tail when nothing is active, and lets you continue the conversation inline until you exit.

chat interactive is the explicit equivalent of bare chat.

Use the lower-level subcommands when you want a more scripted or detached flow:

• chat send --detach submits work and returns immediately
• chat watch and chat resume reattach to in-flight work
• chat transcript, chat list, chat tail, and chat feed expose the raw chat state
• chat reply and chat submit-form let you answer clarifications explicitly

Interactive chat does not support --json. Use the lower-level subcommands for automation, CI, and machine-readable output.

Clarification handling:

• ai_follow_up means the AI wants more freeform input, so reply with chat reply
• system_dialog with info.form means you should call chat submit-form
• ai_answer means the exchange completed successfully

JSON And Non-Interactive Mode

Every command accepts --json. JSON output uses a stable envelope:

{ "ok": true, "data": {} }
{ "ok": false, "error": { "code": "...", "message": "..." } }

Use --non-interactive in scripts and CI.

--workspace <id> and --personal are process-only account overrides. They do not rewrite workspace.selectedId. caffeine workspaces use persists the selection for later CLI and local MCP processes.

Authentication

caffeine auth login opens your browser for an OAuth flow. For CI, remote SSH, or other headless environments, add --device to use the device flow instead.

Tokens are stored in your OS credential store.

MCP Server

Drive Caffeine from Claude Code, Cursor, VS Code, Codex, Windsurf, or another MCP host with the companion MCP server:

npx -y @caffeineai/mcp@dev --version

The CLI and MCP server share the same auth, workspace, project, build, and chat contract. One login flow can cover both tools on the same machine.

Links

Caffeine platform: https://caffeine.ai

This package installs the matching platform binary through npm optional dependencies. Install the main package rather than a platform package directly.

What changed in each release is in CHANGELOG.md, next to this README.