CLI Usage
Get running with the dorkos command, plus the full flag, subcommand, and config reference
CLI Usage
The dorkos command starts your cockpit: 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 dorkosQuick Start
export ANTHROPIC_API_KEY=your-key-here
dorkosDorkOS 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
Prop
Type
The boundary is the fence around your files: DorkOS can read and write inside it, nothing outside. A tunnel (via ngrok) lets you reach your cockpit 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
# Enable Task scheduler
dorkos --tasks
# Verbose logging
dorkos --log-level debug
# Write a local trace file for a bug report
dorkos --debug-trace--debug-trace is a diagnostics flag, not the anonymous telemetry heartbeat: the trace file it
writes never leaves your machine unless you choose to send it. See
Telemetry for what it
records.
Subcommands
install, uninstall, update, marketplace, and cache all talk to a DorkOS server that's
already running. They don't start one for you, so run dorkos first in another terminal (or make
sure it's already running) before using them.
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 validitydorkos 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 defaultsMarketplace
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 projectdorkos marketplace: manage the marketplace sources that list available packages.
dorkos marketplace add <url> [--name <name>] # Register a new source
dorkos marketplace remove <name> # Remove a source
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 publishingdorkos 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 cacheFeedback
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 browserConfig directory
On first run, DorkOS creates ~/.dork/ for persistent storage:
Environment variables
Prop
Type
Config precedence
Configuration is resolved in this order (highest priority first):
- CLI flags (
--port,--dir, etc.) - Environment variables (
DORKOS_PORT, etc.) - Config file (
~/.dork/config.json) - Built-in defaults
Run dorkos config to view the resolved configuration and see which values come from which
source.
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:localThe 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