DocsGPT CLI: a terminal AI agent with approvals

DocsGPT CLI is an open-source (MIT) terminal client for DocsGPT: chat with your agents or ask once from a pipeline, let an agent run commands and edit files with your approval, manage agents and sources as code from CI, benchmark agents with docsgpt-cli bench, and pair a machine as a remote device.

Book a demo Self-host in 5 minutes

curl -fsSL https://docs.ac/install-cli | bash

v1.9.0 · MITInstall guide

Last updated: 2026-10-04

zsh — docsgpt-cli

$ docsgpt-cli "why did the nightly backup fail?"

$ tail -n 50 /var/log/backup.log

→ Approve Always allow tail Always approve Deny Edit

✓ exit 0 · 0.1s

… ERROR: destination /mnt/backup: No space left on device

read_file /etc/backup.conf

→ Approve Always approve Deny Edit

✓ read · 42 lines

The backup target is full and retention is set to 90 days. Free space or lower retention.

Sources: runbooks/backup.md

$ docsgpt-cli "why did the nightly backup fail?"$ tail -n 50 /var/log/backup.log→ Approve Always allow tail Always approve Deny Edit✓ exit 0 · 0.1s… ERROR: destination /mnt/backup: No space left on deviceread_file /etc/backup.conf→ Approve Always approve Deny Edit✓ read · 42 linesThe backup target is full and retention is set to 90 days. Free space or lower retention.Sources: runbooks/backup.md

Install

One command on macOS, Linux and Windows, and it keeps itself up to date.

Install with the one-line script on macOS and Linux or PowerShell on Windows, with Homebrew on macOS, with go install, from a release archive, or from source. Releases ship for macOS (Apple silicon and Intel), Linux (x86-64 and ARM64) and Windows. The CLI updates itself in the background and can roll back a bad update.

Sign in with docsgpt-cli login: an agent API key to chat with that agent, or a personal access token for the agents, sources and bench commands. In CI, DOCSGPT_TOKEN and DOCSGPT_URL replace the login step. The current release is v1.9.0 (2026-10-06).

install script · homebrew cask · go install · release archive · source

# macOS · Linux
curl -fsSL https://docs.ac/install-cli | bash

# Windows (PowerShell)
irm https://docs.ac/install-cli.ps1 | iex

# or: Homebrew (macOS)
brew tap arc53/docsgpt-cli && brew install --cask docsgpt-cli

# sign in with an agent API key or a personal access token
docsgpt-cli login
docsgpt-cli whoami

Chat, ask, pipe

A full-screen chat, or one question in a pipeline, against any agent on your instance.

docsgpt-cli opens a full-screen chat; docsgpt-cli "question" asks once and exits, and anything piped in goes along with it, so git diff | docsgpt-cli "review this" just works. Off a terminal only the answer is printed, ready for the next command in the pipe.

Paste a screenshot or name files to attach them, pick up a chat where you left it, and every answer ends with the documents it drew on. The agents, knowledge and guardrails are the same ones as in the web app; see Agents.

chat · ask once · pipes · attachments · sessions · sources

DocsGPT CLI commands
	Does	Notes
docsgpt-cli	Full-screen chat with an agent	Sessions saved per directory; -c continues the latest, -r picks one
docsgpt-cli "…"	Ask once and exit	Piped input is sent along; off a terminal only the answer is printed
login · logout · whoami	Credentials	An agent API key, or a personal access token for the commands below
agents	Agents as code	list · export · plan · apply · delete · trigger · prompts · tools
sources	Knowledge from CI	list · upload · delete; wait for ingestion, replace the old copy
bench	Test agents' answers	Suites, A/B, model matrix, JUnit. See Benchmarks & Evals
host	Remote device mode	pair · status · revoke · reset · install-service

Local tools, with your approval

The agent can work on your machine; you approve what it does.

In a chat or a one-shot question the agent can run commands and read, edit and write files. Each command, edit and write stops for your approval first, and edits and writes show the diff. Approve it once, allow similar calls for the rest of the session, deny it, or edit the command before it runs.

Approval is the safeguard, so the prompt shows exactly what will run, with hidden control characters made visible. "Always approve" and --auto-approve skip it; keep them for a container, a VM or a throwaway checkout.

approve · always allow · always approve · deny · edit

Local tools and when each asks for approval
	What it does	Asks you
run_command	Runs a shell command	Always
read_file	Reads a text file, or shows the model an image	Outside the working directory, or for files that may hold secrets
edit_file	Replaces exact pieces of text in a file	Always, with the diff first
write_file	Writes a whole file	Always, with a short diff first

Agents and sources as code

Keep agents in a repository, review a plan, apply it from CI, then test it.

Export an agent as YAML (secrets are never exported), commit it, and run agents plan on a pull request and agents apply on merge. A plan shows what each document creates or updates and how its knowledge, tools, prompt and models resolve, and nothing is applied while a reference is missing.

Upload the knowledge in the same pipeline with sources upload --wait --replace, then gate the deploy on docsgpt-cli bench. CI uses a personal access token scoped to just what it deploys.

agents export · plan · apply · sources upload · bench · DOCSGPT_TOKEN

# .github/workflows/docsgpt.yml (excerpt)
env:
  # scopes: agents:write · sources:write · chat:run
  DOCSGPT_TOKEN: ${{ secrets.DOCSGPT_TOKEN }}
  DOCSGPT_URL: ${{ vars.DOCSGPT_URL }}
steps:
  - run: |
      docsgpt-cli sources upload docs/*.md \
        --name "Product docs" --wait --replace
  - run: docsgpt-cli agents apply -f agents/
  - run: |
      docsgpt-cli bench ./bench --target stream \
        --agent-id "$AGENT_ID" --junit bench.xml

Remote Device daemon

Let an agent operate a machine: outbound-only, paired once, approved in the chat.

docsgpt-cli host turns a machine, a server, a Raspberry Pi or a laptop, into a Remote Device your agents can run commands on: a diagnostic, a log, a service restart. It connects outbound and pairs with a one-time code, so it works behind NAT.

In Ask mode every command waits for approval in the DocsGPT chat, where the person is. Full access runs without asking. In every mode the daemon refuses a short safety denylist. Run it as a dedicated user, or in a container or VM, and give it only what agents need.

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

01
Pair with a one-time code
Add the device in Settings › Devices with its approval mode, then run docsgpt-cli host pair on the machine and enter the code. It connects outbound; no inbound port is opened.
host pair · outbound-only
02
Run it, or install it as a service
docsgpt-cli host runs in the foreground; host install-service registers it with systemd, launchd or Task Scheduler so it starts at boot.
systemd · launchd · Task Scheduler
03
Choose the approval mode
Ask pauses every command for approval in the DocsGPT chat; nobody is at the machine, so the daemon follows the server's decision. Full access runs without asking.
Ask · Full access
04
A floor in every mode
The daemon refuses a short safety denylist in every mode: rm -rf /, mkfs, dd to raw disks, shutdown, reboot, a fork bomb.
safety denylist
05
Watch it, then revoke it
host status shows the device and its mode; revoking it in the web app stops the daemon, and a service manager will not restart it.
host status · revoke · reset

How it runs privately

The binary talks only to the DocsGPT instance URL you configure; the Remote Device daemon connects outbound-only to that same instance. 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

A platform team keeps its support agent in a repository. A pull request that edits the agent's prompt runs agents plan for review; merging uploads the changed docs, applies the agent and runs the bench suite, and a failing case blocks the release. On call, an engineer asks the same agent about a failing job from the terminal and approves each command it proposes.

Documentation

Licence

MIT

github.com/arc53/docsgpt-cli

Current version

v1.9.0

released 2026-10-06

Local tools

run · read · edit · write

Platforms

macOS ×2 · Linux ×2 · Windows

Frequently asked questions

What is DocsGPT CLI?: An open-source (MIT) terminal client for DocsGPT: chat with any agent on your instance or ask once from a pipeline, let an agent run commands and edit files with your approval, manage agents and sources as code, benchmark agents with docsgpt-cli bench, and pair a machine as a remote device with docsgpt-cli host. Current version v1.9.0, for macOS, Linux and Windows.
Is it the same as the docsgpt command?: No. docsgpt is the installer's command for running a DocsGPT server (docsgpt up, backups, upgrades). docsgpt-cli is the client that talks to a running instance, yours or DocsGPT Cloud.
Can an AI agent run commands in my terminal safely?: Every command, file edit and file write stops for your approval first, edits and writes with a diff. You can approve once, allow similar calls for the session, deny, or edit the command before it runs. Approval is the safeguard: "Always approve" and --auto-approve remove it, so keep them for a container, a VM or a throwaway checkout.
Can I manage agents from CI?: Yes. Export an agent as YAML, review docsgpt-cli agents plan, and run agents apply from CI with a scoped personal access token in DOCSGPT_TOKEN. Upload the knowledge with sources upload --wait --replace, then gate the deploy on docsgpt-cli bench.
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, and the daemon refuses a short safety denylist in every mode.

See DocsGPT on your documents

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

Book a demo Self-host in 5 minutes

Install

Chat, ask, pipe

Local tools, with your approval

Agents and sources as code

Remote Device daemon

How it runs privately

Example

Frequently asked questions

What is DocsGPT CLI?

Is it the same as the docsgpt command?

Can an AI agent run commands in my terminal safely?

Can I manage agents from CI?

Can an agent operate a server on my behalf?

See DocsGPT on your documents