> For the complete documentation index, see [llms.txt](https://docs.controltheory.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.controltheory.com/controltheory-documentation/dstl8-docs/dstl8-cli.md). # Dstl8 CLI The `dstl8` CLI is the on-ramp to Dstl8. The flow is: **authenticate → add sources → install MCP**. After that, your AI agent can investigate incidents, query logs, and analyze patterns through Dstl8's MCP tools. The CLI also ships an interactive TUI for browsing workspaces, sources, incidents, heatmaps, and logs from a terminal. #### Setup **Install the CLI** Pick the option that matches your environment. Each installs the same `dstl8` binary. | Method | Command | | ------------------------ | --------------------------------------------------------------------------------- | | Homebrew (macOS / Linux) | `brew install control-theory/dstl8/dstl8` | | Shell installer | `curl -fsSL https://install.dstl8.ai/script/dstl8-cli \| sh` | | npm | `npm install -g dstl8` (or `npx dstl8`) | | Nix | `nix profile install github:control-theory/dstl8` | | Manual | Download from [GitHub Releases](https://github.com/control-theory/dstl8/releases) | Verify with `dstl8 version`. **Fast track: `dstl8 setup`** One command to get fully onboarded: ```bash dstl8 setup ``` This walks through four steps — each optional, skip any with `:skip` and re-run `dstl8 setup` anytime to finish later: 1. **Account** — Creates your account via GitHub or browser signup (skipped if you're already logged in) 2. **AI agent integration** — Installs the Dstl8 MCP server into detected AI coding agents (Claude Code, Codex, Cursor, and others) 3. **Data sources** — Auto-detects sources on your machine (Kubernetes contexts, AWS credentials, Vercel/Supabase/GitHub configs) and sets them up 4. **Explore** — Opens the interactive dashboard or web dashboard That's the entire authenticate → add sources → install MCP flow in one guided pass. Prefer to run each piece yourself, or need to script it? The three steps below are the same flow, done manually. **1. Authenticate** Pick the option that matches your situation — you only need one. **If you don't have a Dstl8 account yet:** ```bash dstl8 signup ``` Opens your browser to create a Dstl8 account and organization. Once you're done, the CLI saves a long-lived API token locally, and a `Default` workspace is created for you to start with. **If you already have an account** — for example, you were invited to an existing org, or you're setting up a new device: ```bash dstl8 login ``` Opens your browser to authenticate. If you were invited to an org, accept the invite in the browser first, then run `dstl8 login` to attach the CLI. Either way, confirm with `dstl8 profiles` — the active profile is marked `►`. **2. Add sources** Adding a source is what gets logs flowing into Dstl8. `dstl8 sources add` is an interactive wizard for every source type. It auto-detects local config (`~/.aws/credentials`, `~/.kube/config`, `vercel.json`, `supabase/config.toml`, `.git/config`) and pre-fills sensible defaults. ```bash dstl8 sources add kubernetes dstl8 sources add cloudwatch dstl8 sources add vercel dstl8 sources add supabase dstl8 sources add otlp ``` For pull-based sources (`kubernetes`, `cloudwatch`), the CLI verifies the connection before exiting. For webhook-based sources (`vercel`, `supabase`, `otlp`, `github`), the wizard prints a webhook URL and any auto-generated tokens — paste those into the upstream provider to complete the setup. For scripted setups, pass `--yes` with the relevant flags to skip prompts: ```bash dstl8 sources add cloudwatch --yes \ --name prod-cw \ --aws-region us-east-1 ``` **Confirm logs are flowing.** Pull-based sources should ingest immediately. Webhook sources only start flowing after you paste the webhook URL into the upstream provider, so do that first. ```bash dstl8 sources # source listed and ingesting dstl8 logs fetch -n 5 # recent logs ``` **3. Install MCP** This is the step that connects Dstl8 to your AI agent. `dstl8 install` auto-detects MCP-compatible clients on your machine and configures them: ```bash dstl8 install # interactive picker dstl8 install --all # install to every detected client dstl8 install claude-code # install to a specific client dstl8 install status # see what's installed where ``` Supported clients: | Client | Install command | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Claude Code | `dstl8 install claude-code` | | Claude Desktop | `dstl8 install claude-desktop`, or download `dstl8.mcpb` from the [latest release](https://github.com/control-theory/dstl8/releases/latest) and double-click | | Codex | `dstl8 install codex` | | LM Studio | `dstl8 install lm-studio` | | Cursor | `dstl8 install --include-experimental cursor` | | Windsurf | `dstl8 install --include-experimental windsurf` | Restart your AI client after installing so it picks up the new MCP server. Your AI agent can now query Dstl8. #### The TUI `dstl8 tui` opens an interactive terminal UI for browsing your data without leaving the shell. Most investigation work runs through your AI client once MCP is set up, but the TUI is useful for quick visual checks and one-off navigation. The TUI splits into org-level views (Overview, Workspaces, Incidents, Events, Sources) and workspace views (Dashboard, Incidents, Heatmap, Log Viewer, Events, and — for workspaces with a Kubernetes source — Topology). Use `←` `→` to switch tabs, `↑` `↓` or `j` `k` to navigate, `Enter` to drill in, and `Esc` to go back. `Ctrl+C` quits. **Sources** The org-level Sources tab lists every source connected to your organization. Press `Enter` to drill into streams, then `Enter` again on a stream to see its logs. Press `a` on any source or stream to assign it to a workspace.
**Workspace dashboard** Each workspace has a Dashboard with a Möbius AI summary at the top, a list of active incidents, and the sources feeding the workspace. Press `Enter` on the Möbius summary for a full analysis.
**Incidents** The Incidents tab gives you a sortable, filterable table — Open, Resolved, Closed, or All. Press `s` to change the sort, `f` to cycle filters, and `Enter` on a row to open the incident detail view.
The detail view renders Möbius's full analysis: summary, description, evidence, recommended actions, alongside the impacted resources and event timeline.
**Heatmap** The Heatmap plots sentiment over time by stream, namespace, or service. Anomalies surface as red dots on the affected row. Press `w` to change the time window, `g` to change the grouping, and `Enter` on a row to view the filtered logs for that group.
**Log Viewer** The Log Viewer combines a stacked severity bar chart (1-minute buckets) with a scrollable log table. Press `Enter` on a log line to open a detail modal with full metadata. `c` copies the body to your clipboard.
For the complete list of keybindings across every view, see the [README](https://github.com/control-theory/dstl8-cli#navigation). #### Other CLI commands A handful of commands are useful outside the TUI, especially in scripts and CI. **Piping logs in with tap** `dstl8 tap` pipes *any* logs into Dstl8 without setting up a dedicated source — it auto-detects the format, converts to OTLP, and streams to your org: ```bash kubectl logs -f deploy/api | dstl8 tap heroku logs --tail | dstl8 tap cat app.log | dstl8 tap dstl8 tap --listen # local OTLP endpoint for SDKs/collectors ``` See the full [Tap guide](/controltheory-documentation/dstl8-docs/dstl8-cli/tap.md) for supported formats, the `--listen` OTLP server mode, and per-vendor examples. **Sending and querying events** `dstl8 events` sends and queries platform events — deploy markers, config changes, CI results, and notes on the timeline: ```bash dstl8 events send --type deploy --title "Deployed checkout v1.42" --env prod dstl8 events list --start -7d --type deploy,ci dstl8 events search "rollback" ``` See the [Events guide](/controltheory-documentation/dstl8-docs/events.md) for the full flag reference and CI/CD integration. **Exploring cluster topology** `dstl8 topology` (alias: `topo`) explores the Kubernetes topology captured by cluster agents — the resource tree and blast-radius impact for any component: ```bash dstl8 topology clusters # clusters with topology data dstl8 topology view --kinds deployment,service # the cluster resource tree dstl8 topology impact deployment/checkout/payment-api # what depends on it, what it depends on ``` See the [Topology guide](/controltheory-documentation/dstl8-docs/topology.md) for the web UI and TUI views and the full flag reference. **Tailing and fetching logs** `dstl8 logs tail` streams logs to stdout in real time: ```bash dstl8 logs tail # all logs dstl8 logs tail --source Prod -s error # one source, errors only dstl8 logs tail --stream-name api --search "timeout" ``` `dstl8 logs fetch` pulls a time range and exits — useful for scripts and verifying ingestion: ```bash dstl8 logs fetch --start 24h -n 500 --json dstl8 logs fetch --start 7d --end 24h --source Prod -s error ``` Time arguments accept relative (`30m`, `1h`, `24h`, `7d`) or absolute (`2024-01-15`, `2024-01-15T09:30:00`) values. `--json` produces NDJSON for piping. **Profiles and workspaces** ```bash dstl8 profiles # list configured profiles dstl8 switch # change the active profile dstl8 workspaces # list workspaces dstl8 workspaces create --description "Production monitoring" dstl8 sources assign ``` Configuration lives in `~/.config/dstl8/`. Use `--profile ` on any command to run it against a specific profile without switching. #### More The full command reference, every flag, and release notes live in the [dstl8-cli README](https://github.com/control-theory/dstl8-cli) and on the [releases page](https://github.com/control-theory/dstl8/releases). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.controltheory.com/controltheory-documentation/dstl8-docs/dstl8-cli.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.