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

> Master the different-ai/openwork CLI with this comprehensive guide. Learn to parse arguments, manage configurations, and start your server efficiently.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: how-to-guide
- Published: 2026-08-05

---

**OpenWork provides a built-in Node.js CLI in [`apps/server/src/cli.ts`](https://github.com/different-ai/openwork/blob/main/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](https://github.com/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`](https://github.com/different-ai/openwork/blob/main/apps/server/src/config.ts) reads command-line flags including `--host`, `--port`, `--workspace`, `--read-only`, `--config`, and `--verbose` [[source]](https://github.com/different-ai/openwork/blob/dev/apps/server/src/config.ts#L30).

### Stage 2: Configuration Resolution

**`resolveServerConfig`** merges three configuration layers into a single `ServerConfig` object [[source]](https://github.com/different-ai/openwork/blob/dev/apps/server/src/config.ts#L136):

1. Default values from [`server.json`](https://github.com/different-ai/openwork/blob/main/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]](https://github.com/different-ai/openwork/blob/dev/apps/server/src/cli.ts#L54).

### 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]](https://github.com/different-ai/openwork/blob/dev/apps/server/src/cli.ts#L86).

### Stage 5: Graceful Shutdown

Signal handlers for `SIGINT` and `SIGTERM` stop the heartbeat, clear trusted OpenCode state, and close the server cleanly [[source]](https://github.com/different-ai/openwork/blob/dev/apps/server/src/cli.ts#L108).

## 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`](https://github.com/different-ai/openwork/blob/main/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:

```bash

# 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`](https://github.com/different-ai/openwork/blob/main/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 |

```bash

# 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`](https://github.com/different-ai/openwork/blob/main/apps/server/src/cli.ts)** — Main entry point orchestrating the five-stage pipeline [[source]](https://github.com/different-ai/openwork/blob/dev/apps/server/src/cli.ts)
- **[`apps/server/src/config.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/config.ts)** — Implements `parseCliArgs`, `printHelp`, and `resolveServerConfig` [[source]](https://github.com/different-ai/openwork/blob/dev/apps/server/src/config.ts)
- **[`apps/server/src/server.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/server.ts)** — `startServer` function creating the HTTP API and runtime database [[source]](https://github.com/different-ai/openwork/blob/dev/apps/server/src/server.ts)
- **[`apps/server/src/workspace-init.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/workspace-init.ts)** — Ensures local workspace files exist before startup [[source]](https://github.com/different-ai/openwork/blob/dev/apps/server/src/workspace-init.ts)
- **[`apps/server/src/managed-opencode.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/managed-opencode.ts)** — Spawns temporary OpenCode instances for managed mode [[source]](https://github.com/different-ai/openwork/blob/dev/apps/server/src/managed-opencode.ts)
- **[`package.json`](https://github.com/different-ai/openwork/blob/main/package.json)** (root) — Defines npm scripts wrapping the CLI [[source]](https://github.com/different-ai/openwork/blob/dev/package.json)

## Managed OpenCode Mode

Set `OPENWORK_MANAGE_OPENCODE=1` to enable automatic OpenCode provisioning:

```bash
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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/server.json) via `resolveServerConfig` in [`config.ts`](https://github.com/different-ai/openwork/blob/main/config.ts)
- **Managed OpenCode mode** (`OPENWORK_MANAGE_OPENCODE=1`) automates temporary instance provisioning
- **NPM scripts** in [`package.json`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/workspace-init.ts) skips file creation steps and the server operates in a purely observational mode suitable for safe inspection of production data.