Using the Guru CLI with an AI agent

This page is a conceptual overview of what it looks like to wire the Guru CLI up to work safely with an AI agent — what you'll set up, what decisions you'll make, and what safety controls you have. For the exact commands, configuration details, and troubleshooting tips, see the CLI README on npm. We keep the step-by-step instructions there so they always reflect the current version of the CLI.

What you'll set up

Wiring the CLI up to your agent involves a few steps:

1. Installing the CLI. It's published to npm and installs globally. You'll need a recent version of Node.js; the README has current prerequisites.
2. Configuring credentials. The CLI authenticates with a Guru API token tied to your user account. Your agent will operate with the same permissions you have in Guru — no more, no less.
3. Telling your agent about the CLI. Agents don't use tools they don't know exist. For Claude Code, this means adding context to a CLAUDE.md file. Other agents have equivalents, in addition toAGENTS.md.
4. Setting your safety policy. Choose a write level and turn on audit logging so you have clear boundaries and a record of what your agent does.

The CLI README walks through each step with current commands.

Safety controls you should know about

The CLI is designed to give you clear, adjustable control over what your agent can do. The three controls worth understanding before you get started are write-level policy, audit logging, and credential scoping.

Write-level policy

It's important to note that your agent will never be able to do things your API token doesn't allow. As an added layer of security, write levels let you decide what kinds of operations your agent is allowed to perform within the bounds of your API token. There are four, from most to least restrictive:

• Read-only. The agent can search and retrieve content but can't make any changes. A good starting point for research or browsing agents.
• Safe. Adds low-risk, reversible operations — comments, tags, drafts, and verification. Useful for an annotating agent that's enriching your knowledge base without authoring new content.
• Moderate. Adds content creation, updates, and publishing. Appropriate for an authoring agent you've given real authority to. This is the CLI's default.
• All. Adds destructive operations like deleting collections. Opt in explicitly; most customers shouldn't enable this.

You can tighten or loosen the policy at any time. When your agent hits an operation blocked by the current policy, it can ask you to elevate a single command, which keeps you in the loop for important decisions without requiring a permanent policy change.

Audit logging

Every mutation attempt — whether the CLI allowed it or blocked it — can be written to a structured log file. This gives you a complete record of what your agent did, which is especially valuable while you're building trust with agent-driven workflows. Review the logs periodically to confirm the agent is behaving the way you expect.

Credential scoping

The CLI supports both global credentials (one token for all sessions) and project-scoped credentials (different tokens per project directory). If you're running multiple agents with different responsibilities — say, a read-only research agent and an authoring agent — you can give each one its own Guru identity and its own write level.

Working with different agents

Claude Code

Add context about the Guru CLI to a CLAUDE.md file — either globally, so every Claude Code session on your machine knows about the CLI, or per-project for project-specific guidance. The CLI README includes a starter snippet you can paste in and customize with any team-specific rules (e.g., which Guru collections are authoritative for which topics, or when the agent should prefer searching Guru over its training data).

Cursor, Copilot, and other coding agents

Most modern coding agents support custom instructions or a rules file. The concept is the same as Claude Code's CLAUDE.md: give the agent a short description of the CLI, when to use it, and any team-specific guidance. Check your agent's documentation for the exact file name and format. We generally see that an AGENTS.md file works best for most coding agents.

Custom agents

If you're building your own agent, the CLI's structured JSON output, field-selection flags, schema introspection, and skills system are designed to make integration straightforward. See the README for patterns and examples.

If your agent already has a Guru MCP server connected

If your agent is connected to both the CLI and a Guru MCP server, you'll end up with two overlapping ways to call the same API — which tends to confuse the agent and causes duplicate calls. Pick one per agent:

• Use the CLI if your agent can execute shell commands. Along with the full skills library, safety controls, and audit logging, the CLI is meaningfully lighter on token usage: an MCP server loads the full tool schema into your agent's context on every turn, while the CLI exposes its capabilities on demand. For a surface area as large as Guru's, that difference adds up — both in cost and in how much context is left for your actual work.
• Use the MCP server if your agent can't run shell commands.

If you're going with the CLI, disable the Guru MCP server in your agent's configuration.

Ready to set it up?

Head over to the CLI README on npm for installation instructions, credential setup, and the full command reference. The README is maintained alongside the CLI itself, so it always reflects current behavior.