Herald CLI

Herald is an AI DevOps agent for developers who work from the terminal. Run it from your main code repo to ask questions about your code, services, and local environment without leaving your shell.

Install

Herald requires Node.js 18 or newer.

npm install -g @herald-ai/herald

Start Herald from your main code repo:

cd path/to/your/repo
herald

The first run opens a short setup flow. Herald opens a browser sign-in, automatically saves your CLI API key after login, and offers to connect supported local tools it finds on your machine.

What You Can Ask

Use Herald for questions that usually require jumping between code, git history, logs, and infrastructure tools:

> how is the checkout service wired to the rest of our stack?
> why are pods in the checkout namespace restarting?
> are there early warning signs before checkout latency spikes?
> walk me through how deploys work for the payments service

Herald keeps the session interactive, so you can ask follow-up questions after the first answer.

Local Tool Access

Herald uses your existing local developer tools and credentials. During setup, or later from /config, it can connect to tools such as:

• local git repositories
• Kubernetes through kubectl and your kubeconfig
• Google Cloud through gcloud
• AWS CLI
• Azure CLI
• Grafana
• ClickHouse
• MotherDuck
• Datadog
• Splunk
• New Relic
• Elasticsearch
• Honeycomb
• Vercel
• Supabase
• Render
• Railway

These integrations run locally. You do not need to paste cloud credentials, service account keys, or kubeconfig contents into Herald.

Common Commands

herald

Start an interactive session.

herald ask "why is the checkout service failing?"

Ask one question and print the answer.

For local development against the local backend (requires a suitable Python 3.10–3.12 on PATH for the helper script — see docs for setup):

herald configure

Open the configuration flow.

If you don't have Python 3.11 (or just want to hack on the UI with no backend at all), use the dev mode instead:

bash scripts/dev-herald-local.sh cli --dev

If this is your first time setting up the CLI locally, start with docs/onboarding.md — it has detailed macOS instructions for installing Python 3.11 + PyYAML + the engine package, plus how to invoke the helper script so it uses the right interpreter.

herald tools

Show which local tools Herald can use.

herald --version

Print the installed version.

Configuration

Herald stores local configuration on your machine:

• ~/.herald/config.json stores CLI settings.
• ~/.herald/tool.json stores local tool configuration.
• ~/.config/herald/credentials.json stores your Herald API key.

Use /config inside an interactive session, or run herald configure, to update settings.

Security Notes

Herald runs from your local terminal and uses the repository and tools available in that environment. Local credentials stay managed by the tools that already own them, such as kubectl, gcloud, aws, or az.

The CLI may collect local context needed to answer your question, such as repository metadata, selected file contents, command output from enabled tools, and terminal-provided environment details. Avoid enabling tools or running questions against repositories that contain data you do not want used for the session.

Troubleshooting

If setup does not detect a tool you expect, check that the tool is installed, authenticated, and available on your PATH.

which kubectl
kubectl config current-context

For authentication issues, rerun:

herald configure

For debugging, start Herald with verbose output:

herald --verbose

More product documentation is available at herald.dev/docs/cli.