@herald-ai/herald

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.

Home Screen

After onboarding completes, Herald lands on the Home screen. The Home screen shows:

• A prompt for typing a new investigation question.
• Predictive Issue Detection — background anomaly alerts from configured observability tools (GCP Error Reporting, Datadog, AWS CloudWatch). Alerts appear as selectable notifications; pressing Enter on an alert pre-fills an investigation question with the relevant context.
• Tool suggestions based on a lightweight repo scan (e.g. Kubernetes manifests found but kubectl not configured).
• Version-outdated banners when a newer Herald release is available.
• Slash commands (/config, /tools, /help) are available from the prompt.

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 (Logging, Monitoring, Traces, Error Reporting) through gcloud
• AWS (CloudWatch, CloudTrail) through aws CLI credentials
• Azure through az CLI
• GitHub through GitHub's hosted MCP server
• GitLab through glab CLI
• Grafana through mcp-grafana
• ClickHouse through mcp-clickhouse
• MotherDuck / DuckDB through MotherDuck's hosted MCP server
• Datadog through Datadog's hosted MCP server
• Splunk through Splunk's MCP Server endpoint
• New Relic through New Relic's hosted MCP server
• Elasticsearch through Elastic Agent Builder's MCP endpoint
• Honeycomb through Honeycomb's hosted MCP server
• Vercel through vercel CLI (read-only)
• Supabase through Supabase's MCP server (read-only)
• Render through Render's hosted MCP server (read-only)
• Railway through railway CLI MCP server (read-only)
• Custom user-registered MCP or passthrough tools

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

Predictive Issue Detection

Herald can proactively monitor your configured observability tools for anomalies in the background. When enabled, it periodically queries GCP Error Reporting, Datadog Error Tracking, AWS CloudWatch, Kubernetes, and/or Vercel for new or spiking risk signals. Detected anomalies appear as notifications on the Home screen, and selecting one launches an investigation pre-filled with the relevant error context.

Predictive detection runs automatically when at least one supported observability tool is configured. Results are cached locally at ~/.herald/predictions.json and refreshed when stale (default: every hour).

Common Commands

herald

Start an interactive session (lands on the Home screen).

herald ask "why is the checkout service failing?"

Ask one question and print the answer (one-shot mode; exits after the response).

herald configure

Open the configuration flow.

herald tools

Show which local tools Herald can use.

herald tools --explain

Print a detailed explanation of each configured tool and its capabilities.

herald --version

Print the installed version.

herald --verbose

Start Herald with verbose debug logging to stderr.

herald --no-discovery

Skip automatic tool detection on startup.

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):

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.

Configuration

Herald stores local configuration on your machine:

• ~/.herald/config.json stores CLI settings (engine URL, repo path, command limits).
• ~/.herald/tool.json stores local tool configuration and tool secrets (mode 0600).
• ~/.config/herald/credentials.json stores your Herald API key (mode 0600).
• ~/.herald/predictions.json stores cached predictive alerting results.
• ~/.herald/logs/herald.log stores rolling debug logs (10 MB max, 5 files).
• ~/.herald/shares/*.md stores exported session markdown files.

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

To simulate a fresh install (wipe all local state):

bash scripts/dev-herald-local.sh reset
rm -rf ~/.herald

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