What Is the Purpose of the apps/cli Directory in Craft Agents?

The apps/cli directory contains the craft-cli terminal client, a stand-alone command-line interface that connects to Craft Agents servers via WebSocket RPC, exposes resource management commands, and provides a self-contained mode for running AI agents without external infrastructure.

The apps/cli package in the craft-ai-agents/craft-agents-oss repository serves as the official command-line front-end for the Craft Agents ecosystem. Written in TypeScript and distributed as the craft-cli binary, this tool enables developers to interact with headless servers, manage AI sessions, and automate workflows through bash scripts and CI pipelines. Understanding the purpose of the apps/cli directory reveals how the project bridges server-side AI capabilities with lightweight terminal-based interactions.

WebSocket RPC Client Architecture

At its core, the CLI implements a WebSocket RPC client that communicates with running Craft Agents servers over ws:// or wss:// protocols. The client class resides in apps/cli/src/client.ts and is instantiated throughout the command implementations in apps/cli/src/index.ts (lines 10-12) to provide connect, invoke, and event subscription methods.

This architecture allows the CLI to act as a thin wrapper around the server's JSON-RPC endpoints, translating terminal commands into remote procedure calls without requiring a heavy SDK.

Command Structure and Resource Management

The CLI exposes a comprehensive set of sub-commands defined in apps/cli/src/index.ts (lines 52-86), organized into logical groups for server diagnostics, resource inspection, and session management:

• Server diagnostics: ping, health, and versions verify connectivity and retrieve server metadata
• Resource listing: workspaces, sessions, connections, and sources query the server's current state
• Session lifecycle: session create/delete, send, and cancel manage conversation contexts and message streaming
• Integration testing: validate executes a 21-step integration test against a target server to verify end-to-end functionality

Each command maps directly to server RPC endpoints, returning JSON output when the --json flag is specified for scriptable consumption.

Self-Contained Server Mode

Beyond connecting to external servers, the apps/cli directory provides self-contained operation through the run and validate commands. When invoked without a --url flag, these commands automatically spawn a temporary headless server using the spawnLocalServer helper (implemented in apps/cli/src/server-spawner.ts and referenced in apps/cli/src/index.ts lines 96-105).

The run command exemplifies this workflow: it builds and launches a local server, creates a workspace and session, sends the user's prompt, streams the AI response, and exits—eliminating the need for persistent infrastructure. This makes the CLI suitable for one-off tasks and ephemeral CI jobs.

Environment Configuration and Authentication

The CLI handles configuration through command-line flags and environment variables, parsed by the parseArgs function in apps/cli/src/index.ts (lines 43-56). Key parameters include:

• --url or CRAFT_SERVER_URL for server endpoints
• --token for authentication
• --workspace for default workspace selection
• Provider-specific keys (e.g., ANTHROPIC_API_KEY, OPENAI_API_KEY)

For LLM connections, the CLI can auto-configure providers (Anthropic, OpenAI, Bedrock) from these sources, creating the appropriate LLM_Connection on the server before the first session is used (lines 158-176 in index.ts).

Real-Time Streaming Output

During active sessions, the CLI provides real-time streaming through the sendAndStream function (lines 104-140 in apps/cli/src/index.ts). This implementation:

• Subscribes to session:event messages via WebSocket
• Prints text_delta fragments as they arrive from the AI model
• Displays tool start/result markers for debugging agent behavior
• Handles errors, completion signals, and interruptions with appropriate exit codes

A terminal spinner indicates activity while the agent processes requests, ensuring users receive immediate feedback during long-running operations.

Practical Usage Examples

The following commands demonstrate typical craft-cli workflows:

Connect to a running server and check health:

craft-cli --url ws://127.0.0.1:9100 --token $TOKEN ping

List all workspaces in JSON format for scripting:

craft-cli --json workspaces

Create a session and send a prompt:

SESSION=$(craft-cli --json session create --name "ci-run" | jq -r .id)
craft-cli send $SESSION "Summarize the README"

Run a self-contained agent without external server:

ANTHROPIC_API_KEY=sk-... craft-cli run "Write a short poem about cats"

Execute the full 21-step validation suite:

craft-cli --validate-server --json

Summary

The apps/cli directory in Craft Agents serves as the command-line gateway to the platform's AI capabilities:

• Implements a WebSocket RPC client in src/client.ts for server communication
• Exposes diagnostic, resource management, and session commands via src/index.ts
• Supports self-contained operation through automatic server spawning in src/server-spawner.ts
• Integrates environment variables and LLM provider configuration for seamless authentication
• Provides real-time streaming output with sendAndStream for interactive AI sessions

Frequently Asked Questions

How does the Craft Agents CLI connect to servers?

The CLI establishes WebSocket connections to Craft Agents servers using the client class defined in apps/cli/src/client.ts. It supports both ws:// and wss:// protocols and authenticates via tokens passed through the --token flag or environment variables. The connection is instantiated in apps/cli/src/index.ts (lines 10-12) and reused across command invocations.

Can I use the CLI without running a separate server?

Yes. The run and validate commands support self-contained mode, automatically spawning a temporary headless server via spawnLocalServer in apps/cli/src/server-spawner.ts. This eliminates the need for external infrastructure, making the CLI suitable for one-off tasks and CI pipelines where you want to execute a single prompt and exit.

What environment variables does the CLI recognize?

The CLI recognizes CRAFT_SERVER_URL for server endpoints, CRAFT_TOKEN for authentication, and provider-specific variables like ANTHROPIC_API_KEY or OPENAI_API_KEY for LLM configuration. These are parsed by the parseArgs function in apps/cli/src/index.ts (lines 43-56) and fallback to command-line flags when environment values are absent.

How does the CLI handle real-time AI responses?

The CLI implements real-time streaming through the sendAndStream function in apps/cli/src/index.ts (lines 104-140). It subscribes to session:event messages, prints text_delta fragments as they arrive, and displays tool execution markers. A terminal spinner indicates activity while waiting for the AI to complete generation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}