CLI Usage

The dorkos command starts DorkOS: one line in a terminal, and a browser tab opens with your agents ready to go. No separate server to babysit, no client to configure.

npm install -g dorkos

Quick Start

export ANTHROPIC_API_KEY=your-key-here
dorkos

DorkOS starts on port 4242 and opens your browser automatically. That's the whole workflow for most people, everything below is for when you want to customize it.

Reference

Most people never touch the flags, subcommands, and env vars below. They're here for when you need them, whether that's running on a shared server, scripting an install, or just being curious.

Command-line flags

The boundary is the fence around your files: DorkOS can read and write inside it, nothing outside. A tunnel (via ngrok) lets you reach DorkOS from another device, like your phone, without exposing your whole network.

# Start on a custom port
dorkos --port 8080

# Start with a specific project directory
dorkos --dir /path/to/my/project

# Restrict file access to a project directory
dorkos --boundary /home/user/projects

# Enable tunnel for remote access
dorkos --tunnel

# Turn scheduled tasks on
dorkos --tasks

# Verbose logging
dorkos --log-level debug

# Write a local trace file for a bug report
dorkos --debug-trace

Subcommands

Configuration

dorkos config: manage persistent configuration stored at ~/.dork/config.json.

dorkos config                        # Show all effective settings
dorkos config get <key>              # Get a single config value
dorkos config set <key> <value>      # Set a single config value
dorkos config list                   # Full JSON output
dorkos config reset [key]            # Reset all or a specific key to defaults
dorkos config edit                   # Open config in $EDITOR (your terminal's default text editor)
dorkos config path                   # Print config file location
dorkos config validate               # Check config validity
dorkos config acknowledge-autonomy   # Read what Full autonomy means, and confirm it

dorkos config set follows the same rules as changing a setting in DorkOS itself. It checks the value before saving, so a value a setting cannot hold — or a setting that does not exist — is reported instead of written, and it shows you the value that was actually saved. Every change you make this way is written to your log at ~/.dork/logs/dorkos.log, by name, so you can find out later what moved a setting. Only the setting's name is logged, never its value.

Settings that need you to confirm what they mean ask here too. Starting every new session in Full autonomy is the one that does today: dorkos config set runtimes.defaultTrustStop autonomy is refused until you run dorkos config acknowledge-autonomy, which reads you what it means and asks you to confirm. That needs a real terminal — there is no flag to answer it for you.

Lists are set whole, not item by item. dorkos config set writes one setting at a time, and a list counts as one setting: dorkos config set ui.dismissedUpgradeVersions.0 1.2.3 is refused. To change what is in a list, run dorkos config edit and change it in the file.

dorkos init: an interactive setup wizard for first-time configuration. Walks through your API key, default port, and working directory.

dorkos init
dorkos init --yes    # Accept all defaults

Marketplace

dorkos install / dorkos uninstall / dorkos update: install, remove, and update marketplace packages.

dorkos install <package>                          # Install from any configured source
dorkos install <package> --marketplace <name>     # Install from a specific marketplace
dorkos install <package> --source <url>           # Install from an explicit Git or marketplace.json URL
dorkos install <package> --force                  # Override warning-level conflicts
dorkos install <package> --yes                    # Skip the confirmation prompt
dorkos install <package> --project <path>         # Install into a specific project

dorkos uninstall <package>                        # Remove an installed package
dorkos uninstall <package> --purge                # Also remove preserved data and secrets
dorkos uninstall <package> --project <path>        # Uninstall from a specific project

dorkos update                                     # Check all installed packages for updates (advisory only)
dorkos update <package> --apply                   # Apply an available update
dorkos update <package> --project <path>          # Check or apply within a specific project

dorkos marketplace: manage the marketplace sources that list available packages.

dorkos marketplace add <url> [--name <name>]   # Register a new source (you only)
dorkos marketplace remove <name>               # Remove a source (you only)
dorkos marketplace list                        # List configured sources
dorkos marketplace refresh [<name>]            # Re-fetch one or every source's listing
dorkos marketplace validate <path-or-url>      # Validate a marketplace.json before publishing

add and remove are yours alone. A source is a place DorkOS will download and run code from, so an agent that runs either one is turned down with a plain refusal telling it to ask you. See Marketplace sources.

dorkos package: scaffold and validate marketplace packages before publishing them. See Publishing to the Marketplace for the full walkthrough.

dorkos package init <name> --type plugin|agent|skill-pack|adapter
dorkos package validate <path>

dorkos cache: manage the package clone cache at ~/.dork/cache/.

dorkos cache list                      # Show cache counts and total size
dorkos cache prune [--keep-last-n <N>] # Remove older cached package versions (default: keep 1)
dorkos cache clear                     # Wipe the entire cache

Feedback

dorkos feedback: report a bug or request a feature. It opens a prefilled GitHub issue in your browser with your DorkOS version, operating system, runtimes, and on/off settings already filled in. You review and edit everything before submitting; DorkOS sends nothing on its own.

dorkos feedback              # Report a bug (the default)
dorkos feedback --feature    # Request a feature
dorkos feedback --runtime    # Report a runtime issue (Claude Code, Codex, or OpenCode)
dorkos feedback --print      # Print the URL instead of opening a browser

Operator commands

These let you (or an agent running in any runtime) drive a running DorkOS from the command line: discover what it can do, manage agents, schedule tasks, read activity, and check versions. Every command takes --json for clean, scriptable output (raw JSON on standard output, nothing else). Without --json, you get a readable table. See Your agents can operate DorkOS for the plain-language tour.

dorkos capabilities: ask a running DorkOS which actions it accepts by name.

dorkos capabilities                                  # The catalog as a table (id, title, tier)
dorkos capabilities --json                           # The full catalog as JSON

This is the live list, so it never goes stale the way a docs page can. It is not the whole set of tools DorkOS gives an agent. Scheduled tasks have their own dorkos task commands below. Agent messaging, discovery, and extensions are tools an agent uses from inside a session, or from a connected app like Cursor, and they are not in this catalog at all. The catalog's own output says so, so an agent reading it knows to look elsewhere for the rest.

dorkos call: run any capability in that catalog by its id, whether or not it has its own verb. List the ids with dorkos capabilities first.

dorkos call operator.check_update                    # Run a capability with no input
dorkos call operator.activity_list --input '{"limit":5}'
dorkos call operator.config_patch --input-file ./patch.json   # Read the input from a file ('-' for stdin)
dorkos call marketplace.uninstall --input '{"name":"x"}' --approval <token>

A call that needs your OK comes back with status: approval_required and a token instead of doing the work. Approve it in DorkOS, then run the same call again with --approval <token>. Change the input and the token stops matching, because one approval covers one exact action. See Action Approvals.

dorkos agent: list, inspect, create, and edit agents.

dorkos agent list                                    # List every registered agent
dorkos agent show <path-or-id>                       # Show one agent by id or project folder
dorkos agent create --name <slug> --path <dir>       # Create a new agent
dorkos agent create --name <slug> --path <dir> --template <ref> --display-name "<name>"
dorkos agent update --path <dir> --display-name "<name>"   # Edit self-editable fields
dorkos agent update --path <dir> --color "" --icon ""      # Pass "" to clear a field
dorkos agent update --path <dir> --ceiling act             # Cap what this agent may ever do

--ceiling sets the most an agent is ever allowed to do: observe reads only, act changes things but never deletes them, and destructive is no extra limit, which is where every agent starts. Anything past the line is refused outright, and no approval unlocks it — so it is the way to say "read my repos, never uninstall anything." An agent can tighten its own limit; only you can loosen one.

One edge worth knowing: the limit covers what an agent asks DorkOS to do. An agent that can run terminal commands can still act outside DorkOS. If you want that closed too, turn on Require login (Settings, under Security), which makes every request prove it is you.

dorkos task: list, create, trigger, and inspect scheduled tasks.

dorkos task list                                     # List every scheduled task
dorkos task create --name <name> --description "<text>" --prompt "<text>" --target <agent-or-global> --cron "0 8 * * *"
dorkos task trigger <id>                             # Run a task now
dorkos task runs --limit 10                          # List recent task runs
dorkos task runs --schedule <id> --status failed     # Filter runs by task and status

dorkos room export: save a channel or a direct message as a file you can read, search, and keep. One message per line, as JSON. See Rooms for what's in it.

dorkos room export #backend                          # Save it in the current folder
dorkos room export backend --out ~/archive/backend.jsonl
dorkos room export #backend --out - | grep deploy    # Send it to another command instead

dorkos activity: read the activity feed.

dorkos activity                                      # Recent activity as a table
dorkos activity --actor agent --limit 20             # Only agent activity, most recent 20
dorkos activity --category tasks                     # Filter by category (comma-separated for several)
dorkos activity --type agent.registered              # Filter by event type

dorkos version: show versions.

dorkos version                    # The installed CLI version
dorkos version --check            # The running server version and the latest published version
dorkos version --check --json     # Same, as JSON

When no server is running, dorkos version --check still answers: it reports the CLI version and the last-known latest version from the local update-check cache.

If your DorkOS asks you to sign in

By default DorkOS has no login, and these commands just work. If you turned login on (Settings → Security), the server needs to know it is really you, so give the CLI an API key:

1. In the app, open Settings → Security → API keys and create a key. Copy it right away; it is shown once.
2. Hand it to the CLI one of two ways:

export DORKOS_API_KEY=<your key>          # This shell only

printf %s '<your key>' > ~/.dork/api-key  # Every shell, and agents you run
chmod 600 ~/.dork/api-key                 # Keep it readable only by you

The key file is the better choice when your agents run dorkos commands themselves, because they inherit it without you exporting anything. If a command ever answers "this DorkOS instance has login turned on", that is the missing key talking.

Config directory

On first run, DorkOS creates ~/.dork/ for persistent storage:

Environment variables

Config precedence

Configuration is resolved in this order (highest priority first):

1. CLI flags (--port, --dir, etc.)
2. Environment variables (DORKOS_PORT, etc.)
3. Config file (~/.dork/config.json)
4. Built-in defaults

Docker

Run DorkOS in a Docker container without a local Node.js install:

# From the repository (development)
pnpm docker:build
pnpm docker:run

# Or directly (pack the CLI first: the image installs from a local dorkos-*.tgz)
pnpm --filter=dorkos run build && (cd packages/cli && pnpm pack --pack-destination ../../)
docker build -t dorkos:local .
docker run --rm -p 4242:4242 -e ANTHROPIC_API_KEY=your-key dorkos:local

The container binds to 0.0.0.0 automatically for Docker port forwarding.

Automatic update checks

DorkOS checks the npm registry for new versions each time it starts. When a newer version is available, you'll see a notification in the terminal:

┌───────────────────────────────────────┐
│   Update available: 0.2.0 → 0.3.0    │
│   Run npm install -g dorkos@latest    │
└───────────────────────────────────────┘

The check runs in the background with a 3-second timeout, so it never slows down your startup, and caches results for 24 hours. To update:

npm install -g dorkos@latest

Next Steps