codag-cli

README

codag CLI

Codag compresses noisy log streams into compact incident summaries for AI agents. It is built for the moment when raw distributed-systems logs are too large to fit in context, too expensive to ship directly to a model, or too slow for an agent to reason over line by line.

The CLI can be used directly from a terminal or registered as an MCP server for agents such as Claude Code, Codex, and Cursor.

Install

macOS/Linux/WSL:

curl -fsSL https://codag.ai/install.sh | sh

The installer writes codag to ${HOME}/.local/bin by default, adds that directory to your shell startup file when needed, and shows a no-account codag wrap command you can try immediately.

Native Windows binaries are still published as release ZIP files.

From source:

git clone https://github.com/codag-megalith/codag-cli.git
cd codag-cli
make build
make install

With Go:

go install github.com/codag-megalith/codag-cli@latest

The installer writes a bash completion script to ${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion/completions/codag when the installed binary supports it. To enable completion manually in an existing bash session:

source <(codag completion bash)

To persist it yourself:

mkdir -p "${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion/completions"
codag completion bash > "${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion/completions/codag"

Setup

codag setup
codag wrap -- cat /path/to/app.log

codag setup registers the Codag MCP server with supported agents. It does not sign you in and does not require a Codag account.

If you do not have logs handy yet, try the wrapper with a tiny stream:

yes 'ERROR api db pool timeout active=20 waiting=30 path=/api/orders' | head -20 | codag wrap --service api

Sign in only when you want account-backed features such as capsule/parse mode, cache pre-warm, billing/quota management, or account-linked usage:

codag auth login

Authentication uses Codag's OAuth device flow. Tokens are stored in ~/.config/codag/config.json with file mode 0600.

To opt out of CLI usage telemetry:

codag config set telemetry off
# or for a single shell/session:
export CODAG_TELEMETRY=0

The CLI checks GitHub for newer releases at most once per day when stderr is interactive. It skips MCP/log-output paths and only prints notices to stderr. Disable automatic notices with:

codag config set updates off
# or for a single shell/session:
export CODAG_UPDATE_CHECK=0

Core Commands

Command	Use
codag wrap -- <cmd>	Run any log command and return a compact incident summary.
codag wrap --mode capsule -- <cmd>	Return the structured JSON incident capsule.
codag wrap --mode parse -- <cmd>	Return the templated parse output.
codag onboard	Pre-warm the template cache from recent historical logs.
codag mcp serve	Run the MCP server used by agents after codag setup.
codag disable	Remove Codag MCP tools from known agent configs.
codag auth login	Sign in with the browser device-flow login.
codag auth refresh	Refresh the saved OAuth session.
codag auth logout	Remove saved OAuth tokens.
`codag config <set	get
codag help-llm	Print an agent-pasteable usage guide.
codag version	Print the CLI version.
codag update	Check whether a newer CLI release is available.
codag completion bash	Generate a bash completion script.

Examples

The agent-friendly pattern:

codag wrap -- vercel logs --since=1h
codag wrap -- railway logs --service worker
codag wrap -- aws logs tail /aws/lambda/my-fn --since=30m
codag wrap -- kubectl logs my-pod -n prod --tail=2000

Pipe an existing stream:

vercel logs --since=1h | codag wrap
cat /var/log/app.log | codag wrap --service api

Use a different API or console host:

CODAG_SERVER=http://localhost:8765 codag wrap -- cat app.log
CODAG_CONSOLE=http://localhost:3000 codag auth login

MCP

After codag setup, supported agents can call Codag tools directly instead of fetching raw logs through shell commands. For example, an agent can call tail_kubernetes, tail_aws_logs, or the generic wrap tool and receive a deterministic compact summary instead of thousands of raw log lines.

MCP log tools use the hosted deterministic compact path directly. They do not call the authenticated capsule/parse inference endpoints.

If your Codag org runs out of credits or needs a billing action, MCP tool errors include a stable marker such as CODAG_CREDITS_EXHAUSTED and tell the agent to send you to billing or run codag disable.

Data Handling

Codag sends the log lines you pass to codag wrap, codag onboard, or MCP tools to the configured Codag API server for compression. Provider credentials used by local source connectors stay in your local Codag config unless a provider API request itself requires them.

When you are not signed in, codag wrap in the default compact mode falls back to the hosted free deterministic templating path. The CLI mints and stores a server-issued anonymous cda_... token, calls /v1/free/compact, and reuses the token until you log in. Anonymous --mode capsule and --mode parse still require login because those modes use the authenticated inference pipeline.

Use CODAG_SERVER or codag config set server <url> to point the CLI at a self-hosted, staging, or local API.

The CLI records opt-out usage telemetry through PostHog by default. Events cover command names, command paths, duration, CLI version, OS/architecture, setup flags, and aggregate wrap metrics such as input line count, token estimates, and compression ratio. Failure events include stable error categories and status or exit codes, not raw error messages. Telemetry does not include raw log lines, provider credentials, OAuth tokens, or local config contents. After login, telemetry may be associated with the signed-in Codag account. Disable it with codag config set telemetry off or CODAG_TELEMETRY=0.

Disabling telemetry also sends X-Codag-Retention: off on hosted free compact requests, so the server records metadata-only anonymous usage instead of retaining encrypted raw log lines.

Automatic update checks call the public GitHub latest-release endpoint and store only the last check time/latest version in local config. They can be disabled with codag config set updates off or CODAG_UPDATE_CHECK=0.

Development

make test
make build
make build-all
./bin/codag --help

make build-all cross-compiles macOS, Linux, and Windows binaries for amd64 and arm64 into dist/, with .tar.gz archives for macOS/Linux, .zip archives for Windows, and checksums.txt.

The project is intentionally small: a Go CLI, HTTP client, OAuth device-flow auth, MCP server, and provider/source helpers.