DocsGPT CLI: a terminal AI agent with approvals

DocsGPT CLI is an MIT-licensed Go terminal client for DocsGPT: ask and chat with agents, run an agentic terminal mode in which every command, file read and file write needs human approval, benchmark agents with docsgpt-cli bench, and pair machines as remote-device tools with docsgpt-cli host.

Book a demo Self-host in 5 minutes

brew tap arc53/docsgpt-cli && brew install docsgpt-cli · v1.5.1 · MIT

Last updated: 2026-09-19

zsh — docsgpt-cli ask, agentic mode

$ docsgpt-cli ask --key infra-helper "why did the nightly backup fail?"context: cwd · directory listing · last 3 shell commands (--no-context turns this off)run_command tail -n 50 /var/log/backup.log[1] Approve [2] Deny [3] Edit > _ ⏎ approves✓ approved… ERROR: destination /mnt/backup: No space left on deviceread_file /etc/backup.conf[1] Approve [2] Deny [3] Edit > _✓ approvedThe backup target is full; retention is set to 90 days. Free space or lower retention. Cites: runbooks/backup.md §3

Install

One binary, three channels, three platforms.

Install with Homebrew, download a release binary and run ./docsgpt-cli install to put it on your PATH, or build from source with make build. Releases ship darwin-arm64, linux-amd64 and windows-amd64 binaries. The CLI self-updates automatically, notify-only or off, and can roll back a bad update. Homebrew installs are left to brew upgrade.

Configuration lives in ~/.docsgpt/config.json: one instance URL and any number of named API keys, one per agent. --key picks the agent for a single command and --url points it at another instance, so the same binary reaches staging and production. The current release is v1.5.1 (2026-08-17).

brew · release binary · make build · ~/.docsgpt/config.json

# macOS · Linux · Windows — one binary per release:
# darwin-arm64, linux-amd64, windows-amd64.
brew tap arc53/docsgpt-cli && brew install docsgpt-cli

# or take a release binary and put it on PATH:
./docsgpt-cli install

docsgpt-cli --version    # v1.5.1

# ~/.docsgpt/config.json: one instance URL, many named agent keys
# --url and --key override either for a single command
# self-update: on, notify or off, with rollback (brew installs untouched)

ask and chat

One-shot or multi-turn, against any agent on your instance.

docsgpt-cli ask sends one question to an agent and streams the answer; if the answer contains a command, ask copies it to your clipboard. docsgpt-cli chat keeps a conversation open, with /quit, /clear, /copy and /think. The last of these toggles reasoning-token visibility, which is off by default and available in chat only.

Both use the same agents, knowledge and guardrails as the web app; the CLI is a client, not a second product.

ask · chat · bench · host

DocsGPT CLI commands
	Does	Notes
docsgpt-cli ask	One-shot question to an agent	Streams the answer; agentic mode with approvals; a command found in the answer is copied to your clipboard
docsgpt-cli chat	Multi-turn session with an agent	/quit · /clear · /copy · /think
docsgpt-cli bench	Run a suite directory against an agent	v1 · stream · webhook targets, JSON/JUnit, exit codes, baseline diffs. See Benchmarks & Evals
docsgpt-cli host	Pair this machine as a Remote Device tool	pair · status · revoke · reset · install-service · uninstall-service
keys · config · update · install	Housekeeping	Named API keys, instance URL, theme, banner, auto-update mode; put the binary on your PATH

Agentic terminal mode with approvals

Three tools, each gated by a person.

In agentic mode the agent can use three tools: run_command, read_file and write_file. Every call stops at an approval card with [1] Approve, [2] Deny and [3] Edit. Edit lets you rewrite the command, or the tool's arguments, before it runs.

A blocklist is applied before the prompt, so a match is refused outright rather than offered to you, and --auto-approve does not reach it. It covers rm -rf /, rm -rf /*, mkfs, dd if=, writes to /dev/sd* or /dev/nvme*, shutdown, reboot and the classic fork bomb.

Context enrichment sends the working directory, its listing and your last few shell commands with the question. --no-context turns it off, and with it the tool definitions, so the agent cannot propose an action at all. One flag gives you a plain question and answer. The same approval idea governs the web app's approval gates.

run_command · read_file · write_file — 1 approve · 2 deny · 3 edit

Agentic-mode tools, their approval gate and the destructive-command blocklist
	At the prompt	Before the prompt
run_command	[1] Approve · [2] Deny · [3] Edit — Edit rewrites the command	Checked against the blocklist. A match is refused outright: no prompt, no run, no way past it
read_file	[1] Approve · [2] Deny · [3] Edit — Edit opens the raw JSON arguments	—
write_file	[1] Approve · [2] Deny · [3] Edit; the card previews the first five lines to be written	—

The prompt accepts 1/2/3, a/d/e or y/n, and Enter on its own approves. Anything else denies. --auto-approve skips the prompt but never the blocklist; it is for disposable environments, not production.

bench

Test-driven agent quality from the same binary.

docsgpt-cli bench runs a suite directory against an agent through one of three targets: v1 (POST /v1/chat/completions), stream (POST /stream, SSE) or webhook (posted, then polled to completion). It asserts on answer content, JSON fields, source count, tool usage, latency, tokens, golden snapshots and LLM-as-judge rubrics, with the judge running as its own agent. Output is JSON or JUnit with exit codes; baseline diffs, golden-file recording and A/B agent comparisons make prompt and model changes regression-safe.

Cases may carry attachments. --repeat with --min-pass handles flaky answers, -k and --tags select a subset, --concurrency runs cases in parallel, and docsgpt-cli bench init scaffolds a starter suite. Assertion types, the CI procedure and a sample suite are on Benchmarks & Evals.

docsgpt-cli bench ./bench → JUnit · exit code · baseline diff

Remote Device daemon

Let an agent operate a machine: outbound-only, paired once, audited always.

docsgpt-cli host turns a machine into a Remote Device tool an agent can use: run a diagnostic on a server, read a log, restart a service. It connects outbound to your instance and pairs with a one-time code; no inbound port is opened, so it works behind NAT.

Ask mode pauses every command for approval in the DocsGPT chat. The daemon has no one sitting at it, so the approval happens where the person is. Full access runs without asking. Either way a hard denylist forces an approval prompt for catastrophic commands: rm -rf of /, ~ or $HOME, fork bombs, mkfs, dd to a block device, shutdown, halt, poweroff, init 0/init 6, and git push --force (--force-with-lease passes). Compound commands are split on &&, ||, ; and | and each part is checked on its own. The CLI also refuses a short list of patterns outright, before the server is asked.

Tokens are hashed and revocable and every invocation is in the activity log. Which agents may use a device is governed like any other tool. See Agents.

outbound-only · one-time code · Ask / Full access · denylist · audit log

01
Pair with a one-time code
Add the device in Settings → Tools, then run docsgpt-cli host pair --url https://your-instance on the machine and enter the code. It connects outbound; no inbound port is opened. The token is stored hashed on the server.
host pair · outbound-only · hashed token
02
Run the daemon
docsgpt-cli host runs in the foreground: it polls while idle and streams stdout and stderr while a command runs.
host
03
Keep it running across reboots
host install-service registers it with systemd, launchd or Task Scheduler; host uninstall-service removes it again.
systemd · launchd · Task Scheduler
04
Choose the approval mode
Ask (the default) pauses every command for approval in the DocsGPT chat. There is no human at the machine, so the daemon never prompts locally. Full access runs without asking.
Ask · Full access
05
The denylist applies either way
Catastrophic commands force an approval prompt even in Full access, and the CLI keeps its own floor on the machine.
hard denylist · CLI floor
06
Watch it, then revoke it
host status reads live state from the server; the device page shows the command audit log. host revoke revokes on the server and clears local state, host reset clears local state only. A revoked daemon exits at its next check-in and a service manager will not restart it.
host status · revoke · reset · audit log

How it runs privately

The binary talks only to the DocsGPT instance URL in its config; the Remote Device daemon connects outbound-only to that same instance. Nothing goes to Arc53. On Managed, On-premises and Air-gapped deployments all CLI traffic stays inside your network; on Cloud it goes to your Cloud instance.

The CLI is open source (MIT) and free in every deployment posture; see pricing for the platform itself. Pair it with a self-hosted instance to try it.

Example

An operations engineer pairs a bastion host as a Remote Device in Ask mode. When a backup alert fires, she asks the infra agent what happened; it proposes reading the backup log and the retention config, she approves each read from the chat, and it answers with the cause and the relevant runbook section. Nothing ran that she did not see first, and the session is in the device's activity log.

Documentation

Licence

MIT

github.com/arc53/docsgpt-cli

Current version

v1.5.1

released 2026-08-17 · github.com/arc53/docsgpt-cli/releases

Gated tools

run_command · read_file · write_file

Platforms

darwin-arm64 · linux-amd64 · windows-amd64

Frequently asked questions

What is DocsGPT CLI?: An MIT-licensed terminal client for DocsGPT written in Go: docsgpt-cli ask and docsgpt-cli chat talk to any agent on your instance, an agentic mode lets an agent run commands and read or write files with your approval, docsgpt-cli bench runs benchmark suites, and docsgpt-cli host pairs a machine as a remote-device tool. Current version v1.5.1, for macOS, Linux and Windows.
Can an AI agent run commands in my terminal safely?: Each run_command, read_file and write_file call stops at an approval card with [1] Approve, [2] Deny and [3] Edit, so you see and can change every action before it runs. Enter approves; anything else denies. A blocklist of destructive commands is applied before the prompt and stays active even with --auto-approve, which is a convenience for throwaway environments, not a production setting.
Can I see the model's reasoning tokens?: In chat, yes: /think toggles reasoning visibility, off by default. ask does not show reasoning and has no flag for it.
How do I benchmark agents from the CLI?: Point docsgpt-cli bench at a suite directory: an optional bench.yaml of defaults and one sub-directory per case, each with a case.yaml. Assertions cover answer content, JSON fields, sources, tool use, latency, tokens, golden snapshots and LLM-judge rubrics scored 0–1; output is JSON or JUnit with exit codes and a diff against the previous run. docsgpt-cli bench init scaffolds a starter suite.
Can an agent operate a server on my behalf?: Yes, through docsgpt-cli host. The machine pairs outbound-only with a one-time code; in Ask mode every command waits for your approval in the DocsGPT chat, a hard denylist forces a prompt for catastrophic commands even in Full access, tokens are hashed and revocable, and every invocation is in the device's activity log.

See DocsGPT on your documents

A 30-minute demo of the CLI against your agents, or self-host and run docsgpt-cli ask in five minutes.

Book a demo Self-host in 5 minutes

Install

ask and chat

Agentic terminal mode with approvals

bench

Remote Device daemon

How it runs privately

Example

Frequently asked questions

What is DocsGPT CLI?

Can an AI agent run commands in my terminal safely?

Can I see the model's reasoning tokens?

How do I benchmark agents from the CLI?

Can an agent operate a server on my behalf?

See DocsGPT on your documents