How to Use the OpenWork CLI: Complete Command-Line Interface Guide for different-ai/openwork

OpenWork provides a built-in Node.js CLI in apps/server/src/cli.ts that parses arguments, merges configuration sources, optionally manages an OpenCode process, and starts the HTTP server with graceful shutdown handling.

The different-ai/openwork repository ships with a powerful command-line interface for controlling the OpenWork server from your terminal. This guide covers the CLI architecture, available flags, npm workflow scripts, and practical examples for both development and production use.

CLI Architecture and Execution Flow

The OpenWork CLI follows a five-stage pipeline defined in the source code. Understanding this flow helps troubleshoot configuration issues and extend functionality.

Stage 1: Argument Parsing

The parseCliArgs function in apps/server/src/config.ts reads command-line flags including --host, --port, --workspace, --read-only, --config, and --verbose [source].

Stage 2: Configuration Resolution

resolveServerConfig merges three configuration layers into a single ServerConfig object [source]:

1. Default values from server.json
2. Environment variables
3. CLI flags (highest priority)

Stage 3: Managed OpenCode (Optional)

When OPENWORK_MANAGE_OPENCODE=1 is set, the CLI spawns a temporary OpenCode instance, injects its URL and credentials into the server config, and registers it as trusted [source].

Stage 4: HTTP Server Startup

The startServer function creates the Express-style API that powers the desktop application, MCP endpoint, and workspace runtime database [source].

Stage 5: Graceful Shutdown

Signal handlers for SIGINT and SIGTERM stop the heartbeat, clear trusted OpenCode state, and close the server cleanly [source].

Available CLI Flags

Pass these flags when invoking the CLI directly:

Flag	Description	Example
--host	Bind address for the server	--host 0.0.0.0
--port	TCP port to listen on	--port 9000
--workspace	Add a workspace path (repeatable)	--workspace /path/to/project
--read-only	Disable write operations	--read-only
--config	Path to custom server.json	--config ./custom-server.json
--verbose	Print resolved configuration	--verbose
--help	Show help message	--help
--version	Show version number	--version

Direct CLI Invocation Examples

Run the CLI with node for full control over server behavior:

# Display all available options

node apps/server/src/cli.ts --help

# Start server with default settings (127.0.0.1:8787)

node apps/server/src/cli.ts

# Bind to all interfaces on custom port

node apps/server/src/cli.ts --host 0.0.0.0 --port 9000

# Register multiple workspaces

node apps/server/src/cli.ts --workspace /home/user/project-a --workspace /home/user/project-b

# Run in read-only mode with verbose logging

node apps/server/src/cli.ts --read-only --verbose

# Use custom configuration file

node apps/server/src/cli.ts --config ./config/production-server.json

NPM Workflow Scripts

The root package.json provides convenient shortcuts that set sensible defaults and handle environment setup:

Script	Purpose
pnpm dev	Start desktop UI (@openwork/desktop) in developer mode
pnpm dev:worktree	Dev mode with auto-generated profile for git worktrees
pnpm dev:electron	Launch Electron version of the UI
pnpm dev:den	Boot OpenWork Den backend (control plane)
pnpm dev:den:web	Start Den web UI
pnpm dev:den:mysql	Spin up local MySQL container for Den
pnpm dev:den:api	Run Den API server with required environment variables

# Recommended quick start for development

pnpm dev

# Work across multiple git worktrees without conflicts

pnpm dev:worktree

# Backend-only mode (no UI)

pnpm dev:den

Key Source Files

Understanding these files helps debug issues and contribute to the project:

• apps/server/src/cli.ts — Main entry point orchestrating the five-stage pipeline [source]
• apps/server/src/config.ts — Implements parseCliArgs, printHelp, and resolveServerConfig [source]
• apps/server/src/server.ts — startServer function creating the HTTP API and runtime database [source]
• apps/server/src/workspace-init.ts — Ensures local workspace files exist before startup [source]
• apps/server/src/managed-opencode.ts — Spawns temporary OpenCode instances for managed mode [source]
• package.json (root) — Defines npm scripts wrapping the CLI [source]

Managed OpenCode Mode

Set OPENWORK_MANAGE_OPENCODE=1 to enable automatic OpenCode provisioning:

OPENWORK_MANAGE_OPENCODE=1 node apps/server/src/cli.ts

In this mode, the CLI:

• Creates a temporary OpenCode instance
• Injects connection details into ServerConfig
• Registers the process as trusted for secure communication

This eliminates manual OpenCode setup for local development and CI environments.

Environment Variables

The CLI respects these environment variables for configuration:

Variable	Effect
OPENWORK_DEV_MODE=1	Enable development features and debugging
OPENWORK_MANAGE_OPENCODE=1	Automatically provision OpenCode instance
PORT	Default port (overridden by --port)
HOST	Default host (overridden by --host)

Summary

• The OpenWork CLI entry point is apps/server/src/cli.ts — a standard Node.js script you can run directly or through npm scripts
• Configuration merges CLI flags, environment variables, and server.json via resolveServerConfig in config.ts
• Managed OpenCode mode (OPENWORK_MANAGE_OPENCODE=1) automates temporary instance provisioning
• NPM scripts in package.json provide developer-friendly shortcuts with proper environment setup
• Graceful shutdown ensures clean termination on SIGINT/SIGTERM signals

Frequently Asked Questions

How do I start the OpenWork server on a different port?

Pass the --port flag when invoking the CLI directly: node apps/server/src/cli.ts --port 9000. Alternatively, set the PORT environment variable before running any npm script.

What is the difference between pnpm dev and pnpm dev:den?

pnpm dev starts both the desktop UI and backend server together for full application development. pnpm dev:den runs only the OpenWork Den control plane backend without any UI components, useful for API-focused development or server deployments.

Can I run multiple workspaces with the OpenWork CLI?

Yes. The --workspace flag is repeatable — pass it multiple times to register several workspace paths: node apps/server/src/cli.ts --workspace /path/a --workspace /path/b. Each workspace gets its own runtime database and MCP endpoint.

How does read-only mode work in the OpenWork CLI?

The --read-only flag prevents any write operations to workspace files and databases. When enabled, workspace-init.ts skips file creation steps and the server operates in a purely observational mode suitable for safe inspection of production data.

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