# CLI Usage
Source: https://dorkos.ai/docs/guides/cli-usage

Get running with the dorkos command, plus the full flag, subcommand, and config reference





# CLI Usage [#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.

```bash
npm install -g dorkos
```

## Quick Start [#quick-start]

```bash
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 [#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 [#command-line-flags]

<TypeTable
  type="{
  '--port, -p': { type: 'number', description: 'Port for the server', default: '4242' },
  '--dir, -d': {
    type: 'string',
    description: 'Default working directory',
    default: 'Current directory',
  },
  '--boundary, -b': {
    type: 'string',
    description: 'Restricts file access to this path and its children',
    default: 'Home directory',
  },
  '--tunnel, -t': {
    type: 'boolean',
    description: 'Enable ngrok tunnel for remote access',
    default: 'false',
  },
  '--tasks': { type: 'boolean', description: 'Enable the Task scheduler' },
  '--no-tasks': { type: 'boolean', description: 'Disable the Task scheduler' },
  '--log-level, -l': {
    type: 'string',
    description: 'Log verbosity: fatal, error, warn, info, debug, trace',
    default: 'info',
  },
  '--debug-trace': {
    type: 'boolean',
    description: 'Write a local timing trace file for bug reports (never sent anywhere)',
    default: 'false',
  },
}"
/>

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.

```bash
# 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
```

<Callout type="info">
  `--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](/docs/self-hosting/telemetry#debug-tracing-a-separate-local-only-flag) for what it
  records.
</Callout>

### Subcommands [#subcommands]

<Callout type="info">
  `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.
</Callout>

#### Configuration [#configuration]

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

```bash
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 init`**: an interactive setup wizard for first-time configuration. Walks through your API key, default port, and working directory.

```bash
dorkos init
dorkos init --yes    # Accept all defaults
```

#### Marketplace [#marketplace]

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

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

```bash
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 publishing
```

**`dorkos package`**: scaffold and validate marketplace packages before publishing them. See [Publishing to the Marketplace](/docs/marketplace/publishing) for the full walkthrough.

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

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

```bash
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 [#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.

```bash
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
```

### Config directory [#config-directory]

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

<Files>
  <Folder name="~/.dork">
    <File name="config.json" />
  </Folder>
</Files>

### Environment variables [#environment-variables]

<TypeTable
  type="{
  ANTHROPIC_API_KEY: { type: 'string', description: 'Claude API key (required)' },
  DORKOS_PORT: { type: 'number', description: 'Server port', default: '4242' },
  DORKOS_DEFAULT_CWD: {
    type: 'string',
    description: 'Default working directory',
    default: 'Current directory',
  },
  DORKOS_BOUNDARY: {
    type: 'string',
    description: 'Directory boundary for file access',
    default: 'Home directory',
  },
  TUNNEL_ENABLED: { type: 'boolean', description: 'Enable ngrok tunnel', default: 'false' },
  NGROK_AUTHTOKEN: { type: 'string', description: 'ngrok auth token (required for tunnels)' },
}"
/>

### Config precedence [#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

<Callout type="info">
  Run `dorkos config` to view the resolved configuration and see which values come from which
  source.
</Callout>

### Docker [#docker]

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

```bash
# 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 [#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:

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install -g dorkos@latest
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add -g dorkos@latest
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn global add dorkos@latest
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add -g dorkos@latest
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Next Steps [#next-steps]

<Cards>
  <Card title="Configuration" href="/docs/getting-started/configuration">
    Full configuration reference with all settings.
  </Card>

  <Card title="Tunnel Setup" href="/docs/self-hosting/tunnel-setup">
    Configure ngrok for remote access.
  </Card>

  <Card title="Quickstart" href="/docs/getting-started/quickstart">
    Walk through your first conversation.
  </Card>
</Cards>