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

> Discover the purpose of the apps/cli directory in Craft Agents. Learn how the craft-cli terminal client manages resources and runs AI agents independently.

- Repository: [Craft Ai Agents/craft-agents-oss](https://github.com/craft-ai-agents/craft-agents-oss)
- Tags: internals
- Published: 2026-07-04

---

**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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/apps/cli/src/client.ts) and is instantiated throughout the command implementations in [`apps/cli/src/index.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/apps/cli/src/server-spawner.ts) and referenced in [`apps/cli/src/index.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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:

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

```

List all workspaces in JSON format for scripting:

```bash
craft-cli --json workspaces

```

Create a session and send a prompt:

```bash
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:

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

```

Execute the full 21-step validation suite:

```bash
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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/src/client.ts) for server communication
- Exposes diagnostic, resource management, and session commands via [`src/index.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/src/index.ts)
- Supports self-contained operation through automatic server spawning in [`src/server-spawner.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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.