CLI Commands - OpenCode Portal

Command Structure

openportal [command] [options]

All commands support the standard options like --directory, --port, and --hostname. See Options for the complete list.

Default Command

When run without a command, OpenPortal starts both the OpenCode server and Web UI.

openportal [directory] [options]

Examples

# Start in current directory
openportal

# Start in specific directory
openportal /path/to/project

# Start with custom ports
openportal --port 8080 --opencode-port 9000

# Start in Docker mode
openportal --docker

# Start with custom name
openportal --name my-app -d ./src

Output

Starting OpenPortal...
  Name: my-project
  Directory: /home/user/my-project
  Web UI Port: 3000
  OpenCode Port: 4000
  Hostname: 0.0.0.0
  Mode: Process
Starting OpenCode server...
Starting Web UI server...

✅ OpenPortal started!
   OpenCode PID: 12345
   Web UI PID: 12346

📱 Access OpenPortal at http://localhost:3000
🔧 OpenCode API at http://localhost:4000

Behavior

Checks if an instance is already running for the directory
If already running, displays instance information and URLs
Auto-selects available ports if defaults are taken
Stores instance configuration in ~/.portal.json
Starts both OpenCode server and Web UI

run

Start only the OpenCode server without the Web UI.

openportal run [options]

Use Cases

Running OpenCode as a backend API service
Connecting custom clients to OpenCode
Running in headless environments
Development and testing of OpenCode integrations

Examples

# Start OpenCode server only
openportal run

# Start in specific directory with custom port
openportal run -d /path/to/project --opencode-port 5000

# Run OpenCode in Docker container
openportal run --docker

# Run with custom hostname
openportal run --hostname 127.0.0.1

Output

Starting OpenCode server...
  Name: my-project
  Directory: /home/user/my-project
  OpenCode Port: 4000
  Hostname: 0.0.0.0
  Mode: Process
Starting OpenCode server...

✅ OpenCode server started!
   OpenCode PID: 12345
🔧 OpenCode API at http://localhost:4000

Docker Mode Output

Starting OpenCode server...
  Name: my-project
  Directory: /home/user/my-project
  OpenCode Port: 4000
  Hostname: 0.0.0.0
  Mode: Docker
Starting OpenCode in Docker container...
  Image: ghcr.io/anomalyco/opencode:1.1.3
  Mount: /home/user/my-project -> /home/user/my-project
  Image ghcr.io/anomalyco/opencode:1.1.3 already available locally
  Container ID: a1b2c3d4e5f6
  Container Name: openportal-my-project-abc123

✅ OpenCode server started!
   Container ID: a1b2c3d4e5f6
🔧 OpenCode API at http://localhost:4000

Behavior

Only starts the OpenCode server process or container
Does not start the Web UI
Instance port is set to null in configuration
Instance webPid is set to null in configuration

stop

Stop a running OpenPortal instance.

openportal stop [options]

Selection Logic

If --name is provided, stops the instance with that name
If --directory or -d is provided, stops the instance in that directory
Otherwise, stops the instance in the current directory

Examples

# Stop instance in current directory
openportal stop

# Stop instance by name
openportal stop --name my-app

# Stop instance in specific directory
openportal stop -d /path/to/project

Output (Process Mode)

Stopped OpenCode (PID: 12345)
Stopped Web UI (PID: 12346)

Stopped: my-project

Output (Docker Mode)

Stopped and removed Docker container (ID: a1b2c3d4e5f6)
Stopped Web UI (PID: 12346)

Stopped: my-project

Behavior

Sends SIGTERM to processes for graceful shutdown
For Docker containers, stops and removes the container (timeout: 10s)
Removes instance entry from ~/.portal.json
If process/container is already stopped, displays informational message
Exits with code 1 if no matching instance is found

list

List all running OpenPortal instances.

openportal list

Alias: ls

openportal ls

Example Output

OpenPortal Instances:

ID        NAME              TYPE      PORT  OPENCODE  STATUS        DIRECTORY
------------------------------------------------------------------------------------------------------------------------
abc123    my-project        process   3000  4000      running       /home/user/my-project
def456    api-server        docker    -     5000      opencode      /home/user/api-server
ghi789    web-app           process   8080  9000      running       /home/user/web-app

Status Values

running - Both OpenCode and Web UI are running
opencode - Only OpenCode server is running (from run command)
web only - Only Web UI is running (OpenCode stopped)
stopped - Neither component is running

Column Descriptions

ID - Unique instance identifier
NAME - Instance name (directory basename or custom name)
TYPE - Deployment mode (process or docker)
PORT - Web UI port (- if not applicable)
OPENCODE - OpenCode server port
STATUS - Current running status
DIRECTORY - Working directory path

Behavior

Checks actual process/container status for each instance
Automatically removes stale entries from configuration
Updates ~/.portal.json if stale entries are found
Shows “No OpenPortal instances running.” if no instances exist

clean

Remove stale instance entries from the configuration.

openportal clean

Use Cases

Clean up after processes crashed or were killed externally
Remove orphaned Docker containers
Reset configuration after manual process termination

Example Output

Removed stale entry: old-project (process)
Removed stale entry: test-app (docker)

Config cleaned. 2 active instance(s).

Behavior

Checks each instance in ~/.portal.json
Verifies if processes are running (process mode) or containers exist (docker mode)
For stale Docker instances, attempts to stop and remove containers
Removes entries for instances that are not running
Keeps entries for instances that are still active
Updates ~/.portal.json with cleaned configuration

Help

Display help information.

openportal --help

Short form:

openportal -h

Output

OpenPortal CLI - Run OpenCode with a web UI

Usage: openportal [command] [options]

Commands:
  (default)       Start OpenCode server and Web UI
  run [options]   Start only OpenCode server (no Web UI)
  stop            Stop running instances
  list, ls        List running instances
  clean           Clean up stale entries

Options:
  -h, --help              Show this help message
  -d, --directory <path>  Working directory (default: current directory)
  -p, --port <port>       Web UI port (default: 3000)
  --opencode-port <port>  OpenCode server port (default: 4000)
  --hostname <host>       Hostname to bind (default: 0.0.0.0)
  --name <name>           Instance name
  --docker                Run OpenCode in a Docker container instead of locally

Environment Variables:
  OPENCODE_DOCKER_IMAGE   Docker image to use (default: ghcr.io/anomalyco/opencode:1.1.3)
  DOCKER_HOST             Docker daemon connection (e.g., tcp://localhost:2375)

Examples:
  openportal                               Start OpenCode + Web UI
  openportal .                             Start OpenCode + Web UI in current dir
  openportal run                           Start only OpenCode server
  openportal run -d ./my-project           Start OpenCode in specific directory
  openportal --port 8080                   Use custom web UI port
  openportal --docker                      Run OpenCode in Docker container
  openportal run --docker                  Run only OpenCode server in Docker
  openportal stop                          Stop running instances
  openportal list                          List running instances

Common Command Patterns

Starting Multiple Instances

# Terminal 1 - Start instance for project A
cd ~/projects/project-a
openportal --name proj-a --port 3000

# Terminal 2 - Start instance for project B
cd ~/projects/project-b
openportal --name proj-b --port 3001

# Terminal 3 - Check all instances
openportal list

Docker Workflow

# Start OpenCode in Docker for isolation
openportal --docker

# Later, stop the instance
openportal stop

# Clean up any orphaned containers
openportal clean

API Server Setup

# Run only OpenCode server on custom port
openportal run --opencode-port 5000 --hostname 127.0.0.1

# Connect your custom client to http://127.0.0.1:5000

Production-like Environment

# Run with Docker and custom configuration
openportal --docker \
  --name production-sim \
  --port 80 \
  --opencode-port 8080 \
  --hostname 0.0.0.0 \
  -d /var/www/myapp

Error Handling

Instance Already Running

$ openportal
OpenPortal is already running for this directory.
  Name: my-project
  Type: process
  Web UI Port: 3000
  OpenCode Port: 4000

📱 Access OpenPortal at http://localhost:3000
🔧 OpenCode API at http://localhost:4000

No Instance Found (stop)

$ openportal stop
No instance found.

Unknown Command

$ openportal unknown
Unknown command: unknown
Use --help to see available commands.

Sensitive Directory Mount (Docker)

$ openportal --docker -d /etc
❌ Failed to start OpenPortal: Cannot mount sensitive system directory: /etc

Getting Started

Installation

Core Features

CLI Reference

Guides

​Command Structure

​Default Command

​Examples

​Output

​Behavior

​run

​Use Cases

​Examples

​Output

​Docker Mode Output

​Behavior

​stop

​Selection Logic

​Examples

​Output (Process Mode)

​Output (Docker Mode)

​Behavior

​list

​Example Output

​Status Values

​Column Descriptions

​Behavior

​clean

​Use Cases

​Example Output

​Behavior

​Help

​Output

​Common Command Patterns

​Starting Multiple Instances

​Docker Workflow

​API Server Setup

​Production-like Environment

​Error Handling

​Instance Already Running

​No Instance Found (stop)

​Unknown Command

​Sensitive Directory Mount (Docker)

Build docs developers (and LLMs) love

Command Structure

Default Command

Examples

Output

Behavior

run

Use Cases

Examples

Output

Docker Mode Output

Behavior

stop

Selection Logic

Examples

Output (Process Mode)

Output (Docker Mode)

Behavior

list

Example Output

Status Values

Column Descriptions

Behavior

clean

Use Cases

Example Output

Behavior

Help

Output

Common Command Patterns

Starting Multiple Instances

Docker Workflow

API Server Setup

Production-like Environment

Error Handling

Instance Already Running

No Instance Found (stop)

Unknown Command

Sensitive Directory Mount (Docker)