@cuylabs/cli

A terminal-native AI coding agent with a full interactive TUI, built on @cuylabs/agent-code and @cuylabs/agent-core. Multi-provider (OpenAI, Anthropic, Google), slash commands, streaming, mid-turn intervention, tool approval, skill discovery, sub-agent delegation, persistent sessions, keyboard shortcuts, markdown rendering, and more.

Quick Start

# 1. Install the released CLI
npm install -g @cuylabs/cli

# 2. Install Bun for the OpenTUI path (recommended)
curl -fsSL https://bun.sh/install | bash

# 3. Add a provider key
cat > .env <<'EOF'
OPENAI_API_KEY=sk-proj-...
EOF

# 4. Launch the TUI
cuylabs

# Or one-shot
cuylabs run "summarize this repo" --json

# Check setup
cuylabs doctor

See Getting Started for full install options, .env setup, and monorepo development.

Install Options

1. Released package

npm install -g @cuylabs/cli
curl -fsSL https://bun.sh/install | bash
cat > .env <<'EOF'
OPENAI_API_KEY=sk-proj-...
EOF
cuylabs

• bun is required for the interactive OpenTUI path.
• If Bun is not installed, interactive commands fail fast with a clear error instead of falling back to another renderer.
• The CLI automatically loads .env from the current workspace and infers the provider/default model from config plus environment. Manual export ... is optional, not required.

2. From this monorepo checkout

From the CLI package directory:

cd /path/to/agents-ts/apps/cli
./install.sh
./bin/cuylabs.js

install.sh is a local bootstrap script for this repo today. It:

• checks for node and pnpm
• installs Bun if missing
• runs workspace pnpm install
• builds @cuylabs/cli
• leaves you with a runnable local CLI

The first bootstrap still needs package-registry access because it installs workspace dependencies.

If you want the cuylabs command in your shell to point at this checkout immediately, use the built-in global flag:

cd /path/to/agents-ts/apps/cli
./install.sh --global
cuylabs --help

That global link points to your local source checkout, not the npm release. After source changes, rebuild to keep the linked command current:

cd /path/to/agents-ts
pnpm --filter @cuylabs/cli build
cuylabs

If you already installed the published package globally and want the source version instead, remove the release install first or relink this checkout on top of it:

npm uninstall -g @cuylabs/cli
cd /path/to/agents-ts/apps/cli
./install.sh --global

3. Compile it yourself

From the repo root:

pnpm install
pnpm --filter @cuylabs/cli build
bun --bun apps/cli/bin/cuylabs.js

To run the latest local source globally from the repo build:

cd apps/cli
./install.sh --global
cuylabs doctor

For development:

cd apps/cli
pnpm dev

Runtime Model

The CLI now has a split runtime model:

• bin/cuylabs.js is still the public entrypoint and is intentionally Node-compatible.
• cuylabs, cuylabs tui, and cuylabs team re-exec under Bun so the interactive UI always runs on OpenTUI.
• Non-interactive commands like run, doctor, models, sessions, and config continue to work directly on Node.
• If Bun is missing, interactive commands fail immediately with an installation hint.

That gives us a safe migration path:

• keep the command surface stable
• keep the agent runtime in TypeScript
• make the terminal UX consistently OpenTUI instead of splitting between renderers

Provider/model resolution also stays automatic:

• .env is loaded from the workspace by default
• provider can be inferred from the available API key
• model can come from --model, config, or the provider default
• if multiple provider keys are present, the current inference order is Anthropic, OpenAI, Google, OpenRouter, Azure, xAI, Mistral, then Groq

Build And Release

What gets built

pnpm --filter @cuylabs/cli build

This compiles the CLI into apps/cli/dist/:

• dist/cli.js — main command router
• dist/tui/index.js — interactive TUI entrypoint
• bundled chunks for the OpenTUI renderer path

The published executable remains:

• apps/cli/bin/cuylabs.js

That wrapper decides whether to:

• keep running on Node, or
• hand off to Bun for interactive OpenTUI commands

How a release works

Today the release model is:

1. build @cuylabs/cli
2. publish the package with dist/, bin/, and docs
3. users install with npm install -g @cuylabs/cli
4. users install Bun for interactive use

Provider SDK packaging:

• OpenAI, Anthropic, and Google SDKs are bundled with the CLI
• OpenRouter is loaded dynamically by @cuylabs/agent-core
• until the OpenRouter SDK publishes an ai@6-compatible peer range, users who need OpenRouter should install @openrouter/ai-sdk-provider explicitly alongside the CLI

Where install.sh fits

apps/cli/install.sh is the repo-local bootstrapper.

It is useful for:

• local development
• testing the CLI from source
• validating the Bun/OpenTUI path before packaging changes

It is not yet the remote release installer. A future hosted installer could wrap the same steps behind a curlable script, similar to:

curl -fsSL https://example.com/cuylabs/install.sh | sh

For now, the local version is the safer step because it works directly against this checkout and the current workspace layout.

Documentation

All docs live in docs/:

Getting Started

| Doc | Description | | --- | ----------- | | Getting Started | Install, API key setup, first run | | Command Reference | All CLI commands and slash commands |

User Guide

| Doc | Description | | --- | ----------- | | TUI Guide | Layout, shortcuts, intervention, approval | | Models | Choosing, switching, listing models | | Sessions | Persistence, resume, branch, inspect | | Configuration | Config file, env vars, flags, tool specs | | Server Mode | Local server host, stdio/websocket transports, external clients |

Power Features

| Doc | Description | | --- | ----------- | | Skills | SKILL.md discovery and loading | | Sub-Agents | Delegation profiles | | Teams | Multi-agent coordination | | Plugins | Tools, middleware, commands, lifecycle |

Architecture

| Doc | Description | | --- | ----------- | | Overview | System diagram and source layout | | App Layer | The collect/format/render pattern | | Setup Pipeline | Bootstrap and preflight |

At a Glance

Commands

cuylabs [prompt]             # Interactive TUI (default)
cuylabs run [prompt]         # One-shot, then exit
cuylabs chat [prompt]        # Legacy plain-text mode
cuylabs team [prompt]        # Multi-agent team mode
cuylabs server               # Start a local agent-server host
cuylabs doctor               # Workspace diagnostics
cuylabs capabilities         # Inspect workspace features
cuylabs models               # List available models
cuylabs sessions list        # List saved sessions
cuylabs config show          # Show resolved config

TUI Slash Commands

/help  /status  /model  /tools  /sessions  /resume  /branch
/clear  /compact  /undo  /diff  /skills  /agents  /capabilities
/shortcuts  /quit

Key Features

| Feature | Description | | ------- | ----------- | | Multi-provider | OpenAI, Anthropic, Google — auto-detected from API key | | TUI | OpenTUI under Bun for rich interactive panels and team dashboards | | Intervention | Redirect the agent mid-turn while it's streaming | | Tool approval | Y/N/A prompts for moderate and dangerous tools | | Sessions | Auto-persisted JSONL, resume, branch, inspect | | Skills | SKILL.md discovery with two-phase loading | | Sub-agents | Explorer, coder, planner, runner profiles | | Teams | Multi-agent coordination with task board | | Plugins | Custom tools, middleware, commands — zero build step |

Common Options

cuylabs --model anthropic:claude-sonnet-4-20250514
cuylabs --approval never
cuylabs --tools read-only
cuylabs --continue           # resume last session
cuylabs --cwd /path/to/project
cuylabs --system @./AGENTS.md
cuylabs run "check tests" --server-url ws://127.0.0.1:4647
cuylabs chat --server-stdio node --server-stdio-arg ./server.mjs

See Configuration for the full option reference.