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 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.

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 marketplace: everything to do with marketplace packages lives here. You can install, update and remove packages, see what you have, and manage the sources packages come from.

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

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

dorkos marketplace installed                              # List every installed package, and where
dorkos marketplace installed --verify                     # ...and whether each one's files changed since install
dorkos marketplace check-files <package>                  # Compare a package an older DorkOS installed with the version you installed
dorkos marketplace keep-files <package>                   # Keep files an update couldn't sort as yours (asks first)
dorkos marketplace outdated                               # List only the packages that have an update
dorkos marketplace update                                 # Check every installed package, wherever it's installed
dorkos marketplace update <package> --apply               # Review and install an available update
dorkos marketplace update --apply                         # Review and install every available update
dorkos marketplace update --apply --yes                   # Install without the question (still prints what runs)
dorkos marketplace update <package> --project <path>      # Check or apply within a specific project
dorkos marketplace held-back                              # List packages held back from every session, and why
dorkos marketplace held-back --allow <package>            # Print what it runs, then let it load (asks first)
dorkos marketplace held-back --refuse <package>           # Keep it held back
dorkos marketplace link <path>                            # Run a package from a folder on your computer (asks first)
dorkos marketplace link <path> --replace-installed        # ...setting the installed copy aside while linked
dorkos marketplace unlink <package>                       # Stop running it from the folder (you only)

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

dorkos install, dorkos update and dorkos uninstall are shorter names for the same three commands. They take the same options and do exactly the same thing, so use whichever you like.

installed shows one row per installation. A package you installed for everyone and for two agents shows up three times, and each row says where it lives: global, or the agent's name. A row marked linked is a folder linked to a working copy on your computer. DorkOS never updates a linked package, so update its source instead.

Add --verify to see whether each package's files still match what was installed. The FILES column says as installed, changed (3) when files were edited, removed or added where the package keeps what it runs, or unknown. unknown usually means an older version of DorkOS installed the package and didn't record its files. Run dorkos marketplace check-files <package>. It compares the package with the version you installed, so updates keep your edits. DorkOS records its files only when they all still match that version. Otherwise it changes nothing and tells you why.

A FILES entry like as installed, 2 kept means an update couldn't get the version you had, so it kept 2 files it couldn't tell were yours. Run dorkos marketplace check-files <package> once you're online. It sets aside the files that are exactly what the earlier version shipped, renaming each to end in .dork-old, and keeps the rest. update --apply and uninstall also name any files they kept this way. A package installed from a folder on your computer, or one whose version no longer exists, has no earlier version to sort with, so run dorkos marketplace keep-files <package> instead. It lists the files, marks the ones that still run, asks you, and then makes them yours: updates keep them, and nothing is moved or deleted. For a package held back from every session, it also prints what the package runs, and your yes approves what it discloses now, like a Review. If check-files can still sort the files, keep-files sends you there first. Only you can do this, not an agent; with sign-in on, do it in the app.

For each package, update tells you one of three things: a newer version is available, the package is up to date, or it couldn't be checked (with the reason, for example when you're offline). On its own it only checks. Add --apply to install the updates it finds. It first prints everything each new version runs on its own and asks you, and then installs exactly that. Each package is updated where it's installed. A package installed for one agent is shown with that agent's name, like flow [Alpha].

outdated asks the same question but only prints the packages that are behind, plus any it couldn't check. It never changes anything. Its exit code tells a script or a scheduled job what it found:

A package linked to a working copy is never checked, so outdated lists it under "Linked, not checked" and leaves it out of the exit code. In a script, update only on exit code 1. Exit code 2 means the check failed, not that anything is behind.

installed and outdated both take --project <path> to look only at what one project sees. --project . means the folder you're in, even when DorkOS was started somewhere else. Both also take --json, which prints the result for a program to read:

• installed --json prints { "installed": [...] }, one entry per installation.
• outdated --json prints { "outdated": [...], "unknown": [...], "linked": [...] }. Each entry is one installation's check, with its name, both versions, where it lives, and a note saying why when it couldn't be checked. Packages that are up to date are left out.

link runs a plugin or skill pack straight from a folder on your computer, so you can work on it without reinstalling. It shows the package, the folder, everything it runs and what it replaces, then asks you (--yes skips the question). Add --project <path> to link it for one project only. If you already have the package installed, add --replace-installed: the installed copy is set aside, not deleted. An agent that runs link gets an approval id and a token instead, and runs it again with --approval <token> once you say yes in DorkOS. unlink switches back: your installed copy comes back, or the package is removed. Your folder is never touched, and only you can unlink. installed marks each one dev link → <folder>, and dorkos doctor names any whose folder is gone.

If the folder changes while link is asking you, for example it gains a hook or an extension, nothing is linked and you're asked to run the command again. Your yes covers what you were shown, not what was added after.

link and unlink also take --json, which prints the result for a program to read:

• link --json prints the new dev link: { "name", "type", "scope", "projectPath", "path", "state", "parked", "linkedAt" }. path is the folder's real path, state is active, and parked is { "version" } when an installed copy was set aside, or null. For an agent, it prints the approval request instead: { "status": "approval_required", "approvalId", "approvalToken", "message", "retry" }, and exits with code 1, because nothing was linked yet.
• unlink --json prints { "restored": "installed" } when your installed copy came back, or { "restored": "removed" } when there was none. parkedLeftAt is added when the installed copy couldn't go back because something else is in its place, and names where it still is. leftInPlace: true is added when something else had already taken the link's place: it was left alone.

With --json, a failure prints nothing on standard output. The reason goes to standard error, and the command exits with code 1. With --json and no keyboard to ask, link needs --yes, or it stops without linking.

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 tidies it on its own: after each download it keeps what your installed packages need, plus a waiting update, and removes the rest. prune does the same right away. If DorkOS can't read one of your projects (say, on a drive that isn't plugged in), it removes nothing until it can, and list tells you so.

dorkos cache list                      # Show cache counts and size, and whether cleanup is paused
dorkos cache prune                     # Remove cached packages nothing installed needs
dorkos cache clear                     # Wipe the entire cache

Signed-in browser

dorkos browser: sign in to websites once, in a separate Chrome with an orange frame, so your agents' browsers start already signed in. Agents get the saved sign-ins, never your passwords. These commands work on their own and do not need DorkOS running. Tested on macOS; Windows and Linux are not tested yet.

dorkos browser login [site]      # Open the agent browser, sign in, press Enter to save
dorkos browser login --plain     # For a site that refuses to sign you in otherwise
dorkos browser status [--json]   # Which sites are saved, and how long their cookies last
dorkos browser forget <site>     # Take one site away from your agents (--all for every site)

The full guide, including setup for the claude, codex and opencode command-line tools, is Signed-in Browser.

Space server

dorkos community deploy (early): set up your own space server on Fly, with a Neon database and private file storage. It shows the whole plan before it creates anything. The full guide is Run Your Own Space Server.

Agent files

dorkos harness: share one set of skills, instructions, and hooks with every coding agent you run. You keep them in .agents/ in your project, and DorkOS copies or links them into the folders Claude Code, Codex, Cursor, Gemini, Copilot, and OpenCode each read.

dorkos harness sync                         # Show what is out of date. Writes nothing
dorkos harness sync --fix                   # Set it all up
dorkos harness sync --check --harness codex # Show it for one agent only
dorkos harness sync --fix --strict          # Stop with an error if any hooks were held back

Run it from your project root: it works on the folder you are in, and reads .agents/harness.manifest.json there. --check only reports, so it never writes anything. --fix is what changes files, and it creates that manifest for you if the folder has none.

That manifest holds three things, and nothing else: harnesses, the agents you want files shared with; claudeOnlySkills, the skills you are deliberately keeping in Claude Code's own folder; and hookPolicies, one line per agent saying what to do with your hooks. A policy is generate (DorkOS writes that agent's hooks file), native (the agent reads your hooks itself) or none (DorkOS writes nothing for that agent, and clears away a hooks file it wrote there before). Say nothing about an agent and DorkOS does what it has always done for it. Four older keys — skillWrappers, commandMappings, instructionProjections and skillBundles — are no longer read by anything. Your file still works if it has them; DorkOS just names each one so you can delete it.

When DorkOS sets up a folder for the first time, it turns on the agents it can see you already use — and one more: the agent DorkOS itself runs your sessions on. If your project has only ever used OpenCode, there is nothing of Claude Code's for DorkOS to find, and yet Claude Code is what a DorkOS session in that folder starts. So DorkOS turns it on and says so in one line, and the only file it writes for it is a .claude/CLAUDE.md that points at the AGENTS.md you already keep. Your instructions stay in one file you own; the session reads them.

The same happens on its own the moment you point a DorkOS agent at a folder: DorkOS sets that folder up once, right then, instead of waiting for you to run anything. It never removes files on that pass, and it never asks you to approve anything — it only adds.

Every run looks at which agents your project actually uses. If it finds one you have not turned on — a .cursor/ folder appeared last week, say, or your manifest was written before DorkOS started adding its own agent — it tells you, and tells you how to turn it on:

dorkos harness sync --fix --enable cursor   # Turn Cursor on and set it up, in one go

--enable is the only thing that ever writes to your manifest, and all it does is add the name to the list. Your own spacing, indenting and key order stay exactly as you left them. You can pass it more than once. Nothing is turned on behind your back: without the flag, DorkOS only mentions it. If your manifest has a problem, DorkOS says what is wrong with it and changes nothing.

Some of what DorkOS writes belongs to this computer, not to your project: links into installed packages, the hooks files it rebuilds on every sync. If your .gitignore does not cover them yet, both modes print the exact lines to add, and one flag adds them for you:

dorkos harness sync --fix --write-gitignore # Add the missing lines to .gitignore

It only ever appends, under a comment saying where the lines came from, and it leaves the rest of the file alone. If you ignore .agents/ itself, DorkOS says what that means: your skills stay on this computer, while the links it writes into .claude/skills still get committed — so anyone who clones your project gets links pointing at files they do not have.

Some packages ship hooks: commands your agent runs on its own, before or after it does things. --fix holds those back until you allow them. It sets up everything else the package brought, then prints each command it did not install and how to allow it:

dorkos harness sync --fix --allow-hooks acme-tools   # Install that package's hooks
dorkos harness hooks --list                          # Every package you have decided about
dorkos harness hooks --revoke acme-tools             # Forget one, so you get asked again

--allow-hooks saves your answer, so you only give it once. If DorkOS cannot read your settings file, it tells you what is wrong with it and holds every package's hooks back, and it will not write over a file it cannot read. It is the same answer you would give on the approval card in DorkOS itself, kept in the same place. Held-back hooks are not a failure, so sync still finishes with a success code. Add --strict if you want a script to stop instead.

Some packages you install are for every project, not one. Those live outside your projects, so a normal sync leaves them alone. One flag handles them:

dorkos harness sync --check --global        # Show what would change. Writes nothing
dorkos harness sync --fix --global          # Link them up

It works from any folder, and it does not need a project or a manifest. What it does is put every skill from those packages where DorkOS looks for skills that run on a timer, so a package with a daily job in it actually runs. It names every link it is about to remove before it removes it, and only ever removes links it made itself: a folder you made, or a link you made yourself, is left exactly where it is. A package that is still installed keeps its links even if DorkOS cannot make sense of its settings file, and if DorkOS cannot read the folder your packages live in at all, it stops and removes nothing. Run it twice and the second run does nothing. It does not share those skills with Claude Code, Codex or any other agent yet, and it says so every time.

--global is about those packages and nothing else, so it does not take the flags that are about a folder: --harness, --enable, --allow-hooks, --strict and --write-gitignore are all refused by name rather than quietly ignored.

If you turned plugins on in Claude Code itself, every run tells you about them. Claude Code keeps those to itself, so your other agents cannot see them. DorkOS lists them by name, says which repository each one came from, and prints the command that installs it here so every agent on this project gets it. Nothing is installed for you: you run the command, and DorkOS asks you to approve it first. The report also says which settings file it read, because that can differ between your own terminal and a session an agent started. If your company sets plugins for you in a file DorkOS cannot read, the report says so rather than pretending the list is the whole story.

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 connections: inspect and use only the service access granted to one named agent.

dorkos connections list --agent <agent-id> [--json]
dorkos connections schema <connection-id> --agent <agent-id> [--json]
dorkos connections call <connection-id> <operation-revision-id> --agent <agent-id> --input '{"query":"hello"}'
dorkos connections call <connection-id> <operation-revision-id> --agent <agent-id> --input-file ./input.json
dorkos connections usage --agent <agent-id> [--cursor <cursor>] [--limit 20] [--json]
dorkos connections subscriptions --agent <agent-id> [--cursor <cursor>] [--limit 20] [--json]

Every connection list, schema, call, usage, and subscription command requires the canonical --agent ID. Leaving it out never widens the request to operator access. A call names one stable connection and one reviewed operation revision. If the outcome is unknown, inspect the receipt before deciding whether to try again.

Changes that need you, such as pausing a connection, use the owner-review handoff:

dorkos connections request --action-file ./action.json --idempotency-key <stable-key>
dorkos connections request --action '{"version":1,"kind":"pause","connectionId":"connection-01"}' --idempotency-key <stable-key> --print
dorkos connections status <review-request-id> [--json]

The request command opens the DorkOS app, or prints its local review URL with --print. Review and apply or deny the change there. The CLI can check the opaque request status, but it cannot approve its own request or discover private accounts through the handoff. Reuse the same idempotency key only for the same intended change.

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

A template is copied into the new agent's folder, and that folder is where the agent's sessions run. So before it lands, DorkOS checks what it brings: settings files the sessions load (such as .claude/settings.json with its hooks and permission rules, or a .mcp.json), and skills that run commands or use tools without asking. If it brings any of those, dorkos agent create prints them and asks before creating the agent (--yes skips the question and still prints them). When an agent runs this command, a person has to approve it on a card first; the command prints the --approval retry. An agent from the marketplace is created from the Marketplace in the app, or with dorkos marketplace install, rather than as a template.

What an agent may do — Rooms, Tasks & schedules, Other agents, Messages, Chat connections, Tools & packages, Extension tools, Own chat, DorkOS settings, Safety limits, Permissions, Reach & secrets, and Files & commands — is set with dorkos agent permissions, not dorkos agent update:

dorkos agent permissions <agent>                       # What one agent may do, and why
dorkos agent permissions <agent> set rooms ask         # Give it its own setting for one area
dorkos agent permissions <agent> set files ask         # Its own Files & commands stop
dorkos agent permissions <agent> reset files           # Back to the setting everyone has

The settings every agent shares, and the history of changes, are under dorkos permissions:

dorkos permissions                                     # The preset, every area, and who differs
dorkos permissions set --preset balanced               # Choose a preset
dorkos permissions set tasks ask                       # One area, for everyone
dorkos permissions history --agent <agent>             # Recent changes, each with its id
dorkos permissions undo <id>                           # Undo one of them

See the Permissions guide for the areas, the presets, and the request-card flow. One edge worth knowing: a permission 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 Ask for a password on this computer too (Settings, under Access), 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 → Login & security), the server needs to know it is really you, so give the CLI an API key:

1. In the app, open Settings → Login & 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