CLI Usage Guide
Relevant source files
The following files were used as context for generating this wiki page:
The Orcy CLI is a command-line interface used to interact with the Orcy task management system. It acts as a bridge between the user's shell and the Orcy API server, providing tools for habitat management, mission orchestration, task lifecycle control, and daemon administration. While agents typically interact via the Model Context Protocol (MCP), the CLI is optimized for human-driven workflows, debugging, and system management.
The CLI follows a structured command pattern (e.g., orcy <category> <action>) and requires authentication via environment variables or a .env file to communicate with the backend. It is the primary tool for starting the local server, registering new agents, and performing bulk administrative operations.
Sources: packages/installer/skills/orcy-cli-usage/SKILL.md:1-10, packages/installer/skills/orcy-overview/SKILL.md:95-108, README.md:200-215
Architecture and Data Flow
The CLI operates as a stateless client that sends HTTP requests to the Orcy API. It relies on specific environment variables for context, such as the API URL and security credentials.
The diagram above illustrates the request-response flow where the CLI consumes environment variables to authenticate and route requests to the API server.
Sources: packages/installer/skills/orcy-overview/SKILL.md:83-93, packages/installer/skills/orcy-cli-usage/SKILL.md:6-8
Core Command Categories
The CLI is organized into several functional domains, each handling a specific part of the Orcy hierarchical model.
Server and Daemon Management
The serve command controls the lifecycle of the Orcy API server. It supports running the server in the foreground or as a detached background process.
| Command | Description | Options |
|---|---|---|
orcy serve start | Starts the API server | --port, --host, --detach, --open |
orcy serve stop | Stops a detached server | N/A |
orcy serve status | Checks if the server is active | N/A |
Sources: packages/installer/skills/orcy-cli-usage/SKILL.md:12-38
Habitat and Mission Orchestration
Habitats are top-level containers, and Missions are the kanban cards within them. The CLI provides commands to browse, create, and summarize these entities.
- Habitat Summary:
orcy habitat summary <habitatId>provides a temporal digest of activity, which is the recommended first step before performing actions. - Mission Management: Missions are created with properties like priority, labels, and dependencies, but their status is auto-derived from child tasks.
Sources: packages/installer/skills/orcy-cli-usage/SKILL.md:40-100, packages/installer/skills/orcy-overview/SKILL.md:18-40
Task Lifecycle Control
Tasks are work units claimed by agents. The CLI allows for manual task transitions, which is essential for human review and recovery.
The state diagram shows the task transitions available through CLI commands. The complete command is the "gated path" which validates quality gates.
Sources: packages/mcp/src/tools/instructions.ts:35-50, packages/installer/skills/orcy-cli-usage/SKILL.md:102-160
Configuration and Authentication
The CLI requires an API key for all requests. The identity of the caller is derived from this key server-side to prevent impersonation.
| Variable | Description |
|---|---|
ORCY_API_URL | The base URL of the Orcy API (e.g., http://localhost:3000) |
ORCY_API_KEY | Authentication key generated during agent or admin setup |
ORCY_HABITAT_ID | Default habitat UUID for commands |
ORCY_AGENT_ID | UUID of the agent (used for heartbeat/stats) |
Sources: packages/installer/skills/orcy-overview/SKILL.md:83-93, packages/api/src/test/documentationValidation.test.ts:107-115
Administrative and Troubleshooting Tools
The admin category provides commands for system-wide configuration and bulk data manipulation.
- Webhooks:
orcy admin create-webhookallows integrating Orcy with Slack or Discord by specifying event triggers (e.g.,task.created). - Batch Operations: Commands like
batch-assign-tasksandbatch-delete-tasksfacilitate managing large volumes of work. - Troubleshooting: The
orcy-install doctorcommand (part of the installer package) validates the environment, checking API reachability and credential validity.
Sources: packages/installer/skills/orcy-cli-usage/SKILL.md:245-285, packages/installer/skills/orcy-cli-usage/SKILL.md:304-315
Example: Full Workload Lifecycle
A typical human workflow using the CLI to manage a task from discovery to completion:
# 1. Start background server
orcy serve start --detach
# 2. Get high-level habitat state
orcy habitat summary <habitatId> --since 24h
# 3. Claim a specific task
orcy task claim <taskId>
# 4. Update task to in_progress
orcy task start <taskId>
# 5. Submit work with an artifact
orcy task submit <taskId> \
--result "Fix implemented" \
--artifact-type pr \
--artifact-url "https://github.com/org/repo/pull/1%22
# 6. Complete and verify quality gates
orcy task complete <taskId> --review-note "Verified via CI"
Sources: packages/installer/skills/orcy-cli-usage/SKILL.md:287-302
The Orcy CLI provides a robust environment for managing the complex coordination of AI agents. By centralizing server control, task transitions, and administrative batching into a single tool, it ensures that human pod members can maintain oversight and resolve blockers effectively.