@getguru/cli

Agent-friendly CLI for the Guru API. Returns structured JSON on stdout — designed to be used by AI coding agents (Claude Code, Cursor, Aider, etc.) that have bash and filesystem access.

Proprietary software — see LICENSE.md. Pre-1.0 — expect the output envelope and some commands to change between minor versions; see CHANGELOG.md for what shifted between releases.

Why a CLI?

AI agents with shell access already know how to use CLIs from training data. A CLI is 35x more token-efficient than MCP for the same tasks — no schema injection, no protocol negotiation, no server process. The agent runs a command, gets JSON back, and reasons over it directly.

What You Can Do

| Command Group | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------ | | guru search | Search across Guru cards and external sources — cards, sources, or both; keyword or semantic | | guru cards | List, read, create, update, delete cards; drafts, comments, verification, tags, folder placement, collaborators | | guru collections | List and inspect collections and their group access | | guru folders | Browse folder trees, list items, check permissions (collection-scoped resolution) | | guru agents | List and inspect Knowledge Agents; manage their group access | | guru announcements | List announcements and view read/unread stats | | guru pages | CRUD for pages; manage permissions, drafts, collaborators, and hierarchy | | guru groups | CRUD for groups + member management and collection access | | guru members | List and manage team members | | guru tags | CRUD for tags and tag categories | | guru sources | Inspect sources, discover facets (object types, field values, hierarchies) for search filtering | | guru teams | Team-level stats (card count, trust score) | | guru schema | Runtime JSON Schema introspection for all resource types | | guru config | Manage CLI settings: write-level, audit-log (show, set, unset) | | guru auth | Credential setup, validation, export, and logout |

All commands that accept an ID also accept a human-readable name or title (case-insensitive). Run guru --help for the full command tree or guru <command> --help for details on any command.

Getting Started

Prerequisites

• Node.js >= 22

Install

npm install -g @getguru/cli       # installs the "guru" command globally

After install:

guru --version                    # confirm it's on PATH
guru --help                       # full command tree

Permission errors on macOS? On a stock macOS setup where Node was installed as root, npm install -g fails with EACCES: permission denied. You have three options, cleanest first:

• Use nvm (recommended) — nvm installs Node under your home directory, so npm install -g just works — no sudo needed.
• Change npm's prefix to a directory you own — avoids sudo without reinstalling Node. See npm's official workaround.
• Use sudo — sudo npm install -g @getguru/cli. Works, but leaves root-owned files in your global prefix and you'll need sudo for every future global install or upgrade.

Configuration

Once installed, configure the CLI before use.

Credentials

Get your API token from: https://app.getguru.com/manage/integrations/api-access

# Option 1: Store credentials globally (recommended for most users)
guru auth setup --user [email protected] --token your-api-token

This writes your credentials to ~/.config/guru-cli/credentials.json. You need write access to ~/.config/ in your home directory. On most systems this is fine, but if you get a permission error, check ownership:

ls -la ~/.config/
# If owned by root instead of your user:
sudo chown $(whoami):staff ~/.config

On success you'll see:

{
  "ok": true,
  "data": {
    "success": true,
    "path": "/Users/you/.config/guru-cli/credentials.json",
    "scope": "global"
  }
}

# Option 2: Project-scoped credentials (for multi-agent setups)
guru auth setup --local --user [email protected] --token agent-api-token

This creates .config/guru-cli/credentials.json in the current directory. Use this when you have multiple agents on the same machine, each needing different Guru credentials. The CLI discovers local config by walking up from cwd — just like git finds .git/ — so it works from any subdirectory within the project.

# Option 3: Environment variables (useful for per-command overrides)
export [email protected]
export GURU_CLI_TOKEN=your-api-token

# Or inline for a single command
[email protected] GURU_CLI_TOKEN=your-api-token guru auth status

Credential precedence:

| Priority | Source | Use Case | | ----------- | --------------------------------------------- | ------------------------------------------- | | 1 (highest) | .config/guru-cli/credentials.json (local) | Per-project / per-agent credentials | | 2 | GURU_CLI_USER / GURU_CLI_TOKEN env vars | Per-command overrides | | 3 (lowest) | ~/.config/guru-cli/credentials.json (global) | Global default via guru auth setup |

The CLI reports which source provided credentials when you run guru auth status (the source field will be "local", "env", or "config-file").

Write Policy

Guru itself has role-based access control — your API token is tied to your user account, so you can only call endpoints your Guru administrator has granted you access to. That's the real security boundary.

The write policy is an additional trust-delegation layer for when you hand your credentials to an AI agent. Even if you are allowed to delete a collection, you may not want an autonomous agent doing that on your behalf. The policy lets you control how much authority the agent has.

# Persist globally (recommended)
guru config set write-level moderate

# Persist for this project only (e.g. a restrictive agent)
guru config set write-level none --local

# Or via environment variable
export GURU_CLI_WRITE_LEVEL=moderate

Local write-level settings override global ones, so you can run a restrictive agent in one project directory and a permissive agent in another — each with its own policy.

| Level | What's allowed | Use case | | ---------- | ----------------------------------------------------------------------------- | --------------------------------- | | none | Read-only — all mutations blocked | Browse/research agent | | safe | + additive, easily reversible writes (comments, tags, drafts, verify) | Annotating agent | | moderate | + meaningful changes (create, update, publish cards/folders/collections) | Content authoring agent (default) | | all | + destructive operations (delete cards, collections, folders, groups) | Admin agent — opt in explicitly |

Each level includes everything below it. See Write Policy Details for the full tier breakdown.

Audit Logging

Every mutation attempt — whether allowed or blocked — automatically emits a structured JSON audit line to stderr. For persistent file-based logging:

# Persist globally (recommended)
guru config set audit-log ~/.config/guru-cli/audit.jsonl

# Persist for this project only (each agent gets its own log)
guru config set audit-log ./agent-audit.jsonl --local

# Or via environment variable
export GURU_CLI_AUDIT_LOG=~/.config/guru-cli/audit.jsonl

Like write-level, audit-log can be scoped per project so each agent writes to its own log file.

See Audit Logging Details for the full schema and examples.

Verify It Works

which guru              # Confirm the binary is on PATH
guru --help
guru auth status        # Validates credentials + shows current write level
guru collections list   # A safe read-only command to confirm API access

Teaching Your AI Agent About Guru

The guru CLI is self-documenting at runtime, but your AI agent needs to know it exists. You can tell it directly in a prompt:

Use the guru CLI (installed globally) to search our knowledge base. Run guru --help to see what's available.

The agent will take it from there. But to make this automatic — so you don't have to repeat yourself every session — you need a CLAUDE.md file.

Setting Up CLAUDE.md

CLAUDE.md is the system prompt for Claude Code. It defines how your agent behaves — what tools it knows about, what conventions it follows, and what boundaries it respects. Adding Guru to CLAUDE.md means the agent is always aware of your knowledge base without you having to mention it.

Here's a starting point you can add to a CLAUDE.md file in any project where you want the agent to use Guru. To make it available from any folder where you open Claude Code, add it to ~/CLAUDE.md instead. Use this as-is or adapt it to fit your team's workflow — it's a baseline, not a prescription:

## Guru Knowledge Base

The `guru` CLI is installed globally for accessing the Guru knowledge base. It returns structured JSON and is designed for agent use.

### Skills — ALWAYS check first
Before running guru commands for any multi-step task, **always** check for an existing workflow recipe:
1. Run `guru skills list` to see available skills
2. Run `guru skills show <name>` to read the skill that matches your task
3. Follow the skill's steps — do not improvise a workflow when a skill already exists

Skills encode tested, multi-step workflows (export, import, agent impersonation, page authoring, etc.).
Only fall back to ad-hoc commands when no skill matches what you're trying to do.

### Command reference
- Run `guru --help` for the full command tree
- Before running any guru subcommand for the first time in a session, run `<subcommand> --help` to confirm the exact
  syntax, options, and argument order. Don't guess — check first.
- Run `guru schema` for runtime JSON Schema introspection of all resource types
- Run `guru auth status` to verify credentials are configured
- All output is JSON: `{ "ok": true, "data": ... }` on success, `{ "ok": false, "error": ... }` on failure
- Use `--fields <list>` on any command to reduce output to only the fields you need
- Use `--dry-run` on any command to validate inputs without making API calls
- Use `--elevate` on any mutation to temporarily override the write-level policy for that single command
- **Never use `--elevate` on your own.** Only use it when the user has explicitly instructed you to,
  or when you detect the intended operation is blocked by the current write level — in which case,
  ask the user for permission before proceeding. The human must always be in the loop for elevation.
- Write operations are gated by a configurable write level (see `guru config show`)

Going Further: Shaping How Your Agent Uses Guru

The snippet above is the minimum — it tells the agent the CLI exists. But CLAUDE.md is more than a tool registry. It's where you define when, why, and how the agent interacts with Guru. Think of it as onboarding a new team member who happens to have perfect recall of every CLI flag.

For example, you might add instructions like:

## How to Use Guru

- Before writing any new documentation, search Guru first to avoid duplicating existing content
- When you find outdated information in a card, add a comment noting what changed — don't silently ignore it
- Use the "Engineering" collection for technical docs; use "Product" for specs and PRDs
- Always use `--fields` to keep output concise — don't dump entire cards into context
- Write level is set to `safe` — you can read and comment, but don't create or delete cards without asking me first
- When answering questions about our processes, check Guru before relying on your training data

This turns a generic coding agent into one that actively maintains your knowledge base, follows your team's conventions, and knows its own boundaries. The more specific you are in CLAUDE.md, the more useful the agent becomes.

Warning: Guru MCP Server Conflict

If you also have a Guru MCP server configured, your agent will see two overlapping tool surfaces for the same API — MCP tools injected automatically and CLI commands via shell. This causes confusion, duplicated calls, and unpredictable behavior. Use one or the other per project, not both. If you're using the CLI, disable the Guru MCP server in your agent's MCP configuration.

Usage Reference

Output Format

All commands return structured JSON. Success:

{
  "ok": true,
  "data": [
    {
      "id": "abc-123",
      "name": "Engineering"
    }
  ]
}

Error (printed to stderr):

{
  "ok": false,
  "error": {
    "code": "HTTP_401",
    "message": "Guru API 401: Unauthorized (https://api.getguru.com/api/v1/collections)"
  }
}

Exit Codes

| Code | Meaning | | ---- | -------------------------------------------------- | | 0 | Success | | 1 | API error (4xx/5xx, except auth) | | 2 | Auth error (401, 403, or missing credentials) | | 3 | Input validation error | | 4 | Internal/unknown error | | 5 | Policy violation (mutation blocked by write level) |

Common Flags

| Flag | Available on | Description | | --------------------------- | --------------------------------- | ------------------------------------------------------------------------- | | --fields <list> | All commands | Comma-separated fields to include in output | | --collection <id-or-name> | Folder commands | Scope to collection(s) — comma-separated for multiple | | --folder <id-or-title> | Cards create/create-draft | Place card into folder after creation | | --mode <mode> | Search | What to search: cards, sources, or both (default: both) | | --strategy <strategy> | Search | Search algorithm: keyword or semantic (default: keyword) | | --collection-id <id> | Search | Scope to collection UUID (repeatable) | | --source-id <id> | Search | Scope to source UUID (repeatable) | | --source-type <type> | Search | Filter by source type string (repeatable) | | --folder-id <id> | Search | Filter by folder UUID (repeatable, cards mode only) | | --from <date> | Search | Modified after date (ISO-8601 or relative: 7d, 30d) | | --to <date> | Search | Modified before date (ISO-8601 or relative) | | --include-content | Search | Include full document content in results | | --include-facets | Search | Include facet metadata in response | | --include-snippets | Search | Include result snippets | | --ndjson | List/search commands | One JSON object per line (NDJSON) | | --dry-run | All commands | Validate inputs, show what would execute, no API calls | | --page-all | List commands | Fetch all pages instead of just page 1 | | --page-limit <n> | List commands | Max pages to fetch (default: 10) | | --page-delay <ms> | List commands | Throttle between pages in ms (default: 100) |

Write Policy Details

When a mutation is blocked, the error message tells the agent exactly what level is required:

{
  "ok": false,
  "error": {
    "code": "POLICY_VIOLATION",
    "message": "Mutation blocked: 'cards archive' requires write level 'all', current level is 'moderate'"
  }
}

Safe — additive, low-risk, easily reversible:

• Card annotations: cards add-comment, cards reply-comment, cards resolve-comment, cards unresolve-comment, cards verify, cards add-tag, cards add-to-folder, cards add-collaborator
• Drafts: cards create-draft, cards set-draft-context, cards add-draft-collaborator
• Tags: tags create, tags create-category
• Access: groups add-members, agents add-group, collections add-group

Moderate — meaningful changes, recoverable:

• Card lifecycle: cards create, cards publish, cards unverify
• Card removals: cards delete-comment, cards delete-reply, cards remove-tag, cards remove-from-folder, cards remove-collaborator, cards remove-draft-collaborator, cards delete-draft
• Structure: folders create, folders update, collections create, collections update
• Access changes: collections update-group, collections remove-group
• Agents: agents update-group, agents remove-group
• Groups: groups create, groups update, groups remove-member
• Other: announcements create, tags update, tags update-category, members invite

Destructive — irreversible or high-blast-radius:

• cards archive, folders delete, collections delete, tags delete-category, groups delete, members remove

Per-command allowlist

To permit a specific destructive command without bumping the whole write level to all:

export GURU_CLI_ALLOWLIST="cards archive,folders delete"
# or:
guru config set allowlist "cards archive"

Entries are full command paths; invalid entries are warned and dropped. Env + local + global sources are merged. Allowlisted runs show "allowlist": true in their audit line.

Audit Logging Details

# Audit lines appear on stderr, tagged with _audit: true
guru cards verify abc-123 2>/tmp/audit.log
cat /tmp/audit.log

{
  "_audit": true,
  "ts": "2026-03-19T14:32:01Z",
  "command": "cards verify",
  "args": ["abc-123"],
  "tier": "safe",
  "allowed": true
}

Audit lines are emitted automatically with zero configuration. When file-based logging is configured, the same line is written to both stderr and the file. If the file is unwritable, the CLI warns to stderr but doesn't block the operation (fail-open).

| Field | Description | | --------- | -------------------------------------------------------------- | | _audit | Always true — distinguishes audit lines from error output | | ts | ISO 8601 timestamp | | command | Full command path (e.g. cards archive) | | args | Positional arguments only (no option values, no credentials) | | tier | safe, moderate, or destructive | | allowed | Whether the operation was permitted by the current write level | | elevated | Present + true when --elevate flipped an otherwise-blocked run | | allowlist | Present + true when the command was permitted via the allowlist |

Examples

Detailed usage examples for each command group, followed by multi-step agent workflow recipes.

Search

# Default: cards + sources together (keyword)
guru search -t "onboarding"                                    # Both + keyword
guru search -t "onboarding" --strategy semantic                # Both + semantic

# Mode: choose what to search
guru search -t "deploy" --mode cards                           # Cards only (keyword)
guru search -t "deploy" --mode cards --strategy semantic       # Cards only (semantic)
guru search -t "deploy" --mode sources                         # Sources only (keyword)

# Scope: filter by collection, source, or folder
guru search -t "deploy" --collection "Engineering"             # Scope to collection by name
guru search -t "deploy" --collection-id <uuid>                 # Scope to collection by UUID
guru search -t "deploy" --collection-id <uuid1> --collection-id <uuid2>  # Multiple collections
guru search -t "forecast" --source-type Salesforce             # Filter by connector type
guru search -t "agent" --mode cards --folder-id <uuid>         # Cards in a specific folder

# Date filtering
guru search -t "pricing" --from 30d                            # Modified in last 30 days
guru search --from 2026-01-01T00:00:00.000Z --to 2026-03-01T00:00:00.000Z  # Date window

# Source facet filtering (two-step: discover, then filter)
guru search -t "pipeline" --include-facets                     # Step 1: get facet buckets
guru search -t "pipeline" --facet-field-id <id> --facet-value "Enterprise"  # Step 2: apply facet

# Content and output options
guru search -t "deploy" --include-content                      # Include full document content
guru search -t "deploy" --include-snippets                     # Include result snippets
guru search -t "deploy" --fields id,title --ndjson             # Minimal fields, NDJSON output
guru search -t "deploy" --max-results 50 --start-index 25     # Pagination

Search routing: guru search routes to different API endpoints based on --mode and --strategy:

• --mode both --strategy keyword (default) → POST /search/documents
• --mode both --strategy semantic → POST /search/semantic/documents
• --mode cards --strategy keyword → POST /search/cards
• --mode cards --strategy semantic → POST /search/semantic/cards
• --mode sources → POST /search/sourcemgr (keyword only — no semantic source endpoint)

Flag conflicts: Some flags only apply to certain modes. For example, --folder-id requires --mode cards (folders are a card concept), and --source-type cannot be used with --mode cards. The CLI validates these and returns clear error messages.

Collections

guru collections list                         # List all collections
guru collections list --page-all              # Fetch all pages (not just page 1)
guru collections get <id-or-name>             # Get a collection by ID or name
guru collections groups <id-or-name>          # List groups with access

Folders

guru folders list                             # List all folders (page 1)
guru folders list --collection "Engineering"  # Folders in a specific collection
guru folders list --page-all                  # Fetch all pages
guru folders list --page-all --page-limit 20  # Fetch up to 20 pages
guru folders get <id-or-title>                # Get a folder by ID or title
guru folders get "Coding Agents" --collection "Engineering"  # Resolve by name within a collection
guru folders items <id-or-title>              # List items (cards + sub-folders)
guru folders items "Coding Agents" --collection "Engineering"  # Items in a collection-scoped folder
guru folders items <id-or-title> --type card  # Only cards
guru folders items <id-or-title> --type folder # Only sub-folders
guru folders parent <id-or-title>             # Get parent folder
guru folders permissions <id-or-title>        # List folder permissions
guru folders effective-permissions <id-or-title> # Inherited + direct permissions

Collection-scoped resolution: Folder names aren't unique across collections. Use --collection on get, items, parent, permissions, and effective-permissions to resolve a folder name within a specific collection. UUIDs always work without --collection. When listing folders with --collection, the output includes a section field showing which board group section the folder belongs to.

Cards

# List cards (with filtering)
guru cards list                                              # All cards (first page)
guru cards list --collection "Product Design"                # Cards in a collection by name
guru cards list --collection "Product Design" --from 7d      # Modified in last 7 days
guru cards list --folder-id <uuid>                           # Cards in a specific folder
guru cards list --search "onboarding"                        # Keyword filter
guru cards list --fields id,preferredPhrase,lastModified     # Specific fields
guru cards list --ndjson                                     # Streaming output

# Read
guru cards get <cardId>                       # Get a card by ID (extended view)
guru cards unverified                         # List cards needing verification
guru cards unverified --fields id,preferredPhrase  # Just titles of stale cards
guru cards comments <cardId>                  # List comments on a card (threaded)
guru cards verifiers <cardId>                 # List verifiers assigned to a card
guru cards folders <cardId>                   # List folders containing a card

# Version history (audit trail, drift detection, diff/restore)
guru cards versions <cardId>                  # List a card's revision history
guru cards get-version <cardId> 3             # Snapshot at a specific integer version
guru cards get-last-verified-version <cardId> # Snapshot from when the card was last verified

# Comments (write-back for agent observations)
guru cards add-comment <cardId> --content "Step 3 is outdated — we use Terraform now"
guru cards reply-comment <cardId> <commentId> --content "Good catch, I'll update this"
guru cards delete-comment <cardId> <commentId>  # Delete a comment
guru cards delete-reply <cardId> <commentId> <replyId>  # Delete a reply

# Comment status
guru cards resolve-comment <cardId> <commentId>    # Mark comment as resolved
guru cards unresolve-comment <cardId> <commentId>  # Reopen a resolved comment

# Verification lifecycle
guru cards verify <cardId>                   # Confirm card is still accurate (resets timer)
guru cards unverify <cardId>                 # Mark card as needing re-verification

# Folder placement
guru cards add-to-folder <cardId> <folderId>  # Add a card to a folder
guru cards remove-from-folder <cardId> <folderId>  # Remove a card from a folder

# Tags on a card
guru cards tags <cardId>                      # List tags on a card
guru cards add-tag <cardId> <tagId>           # Add a tag to a card
guru cards remove-tag <cardId> <tagId>        # Remove a tag from a card

# Draft lifecycle (uses /drafts API — drafts appear in "My Drafts" in webapp)
guru cards create-draft --title "..." --content "<p>...</p>" --collection <collectionId>
guru cards list-drafts                        # List your drafts via GET /drafts
guru cards get-draft <draftId>                # Get a draft by ID
guru cards delete-draft <draftId>             # Delete a draft
guru cards publish <draftId>                  # Publish draft -> creates card with associatedDraftId

# Draft publishing context (collection, shareStatus, folders, tags)
guru cards draft-context <draftId>            # Get publishing context
guru cards set-draft-context <draftId> --collection <colId> --share-status TEAM

# Draft collaborators
guru cards draft-collaborators <draftId>      # List collaborators on a draft
guru cards add-draft-collaborator <draftId> [email protected]
guru cards remove-draft-collaborator <draftId> <collaboratorId>

# Create / Archive (published cards)
# 'cards create' creates a draft, sets its publishing context, and publishes it
# under the hood — same flow the Guru webapp uses. Pass --draft to stop after
# the draft step. Mid-flow failures leave the draft in place; retry with
# 'guru cards publish <draftId>'.
guru cards create --title "..." --content "<p>...</p>" --collection <collectionId>
guru cards create --title "..." --content "<p>...</p>" --collection <collectionId> --folder <folderId>
guru cards create --title "..." --content "<p>...</p>" --collection <collectionId> --tags t1,t2
guru cards create --title "WIP" --content "<p>...</p>" --collection <collectionId> --draft
guru cards archive <cardId>                   # Archive a card (soft-delete; reversible)
# Editing a published card via CLI is intentionally not supported — the webapp's
# multiplayer editor would silently overwrite API writes. Edit in the webapp.

# Collaborators on published cards
guru cards collaborators <cardId>             # List collaborators
guru cards add-collaborator <cardId> [email protected]
guru cards remove-collaborator <cardId> [email protected]

Agents (Knowledge Agents)

# Read
guru agents list                                       # List all Knowledge Agents
guru agents list --fields id,name,description          # Just names and descriptions
guru agents list --ndjson                              # One agent per line
guru agents get <agentId>                              # Get full agent details (tone, prompt, sources)
guru agents get "HR Agent"                             # Get by name (case-insensitive)
guru agents list-groups <agentId>                      # Groups with access to an agent
guru agents list-files <agentId>                       # Files attached to an agent

# Group access management
guru agents add-group <agentId> <groupId>              # Grant a group access
guru agents update-group <agentId> <groupId> --role viewer   # Change a group's role
guru agents remove-group <agentId> <groupId>           # Revoke a group's access

# Workflow: discover agents to see what's available in your workspace
guru agents list --fields id,name

Announcements

guru announcements list                      # List all announcements (card content stripped)
guru announcements list --fields announcementId,cardTitle,percentRead  # Just titles and read %
guru announcements stats <announcementId>           # Who read it, when
guru announcements stats <announcementId> --fields readCount,unreadCount  # Just counts

Groups

# Read
guru groups list                              # List all groups
guru groups get <id-or-name>                  # Get a group by ID or name
guru groups members <id-or-name>              # List members of a group
guru groups members "Engineering" --fields email,firstName,lastName  # Just names
guru groups collections <id-or-name>          # Collections a group has access to

# Create / Update / Delete
guru groups create --name "Platform Team"     # Create a new group
guru groups update "Engineering" --name "Platform"  # Rename a group
guru groups delete "Engineering"              # Delete a group

# Member management
guru groups add-members "Engineering" --emails [email protected],[email protected]  # Add members
guru groups remove-member "Engineering" [email protected]  # Remove a member

Members

guru members list                             # List all team members
guru members list --ndjson --fields email,status  # Stream emails and statuses

Tags

# Read
guru tags list                                # List all tag categories and tags
guru tags list --fields name,tags             # Just category names and their tags
guru tags list --ndjson                       # One category per line
guru tags get <tagId>                         # Get a single tag by ID

# Tag CRUD
guru tags create --category <categoryId> --value "Backend"   # Create a tag in a category
guru tags update <tagId> --value "Platform"                  # Rename a tag

# Category CRUD
guru tags create-category --name "Engineering"               # Create a tag category
guru tags update-category <categoryId> --name "Platform"     # Rename a category
guru tags delete-category <categoryId>                       # Delete a category + all its tags

Teams

guru teams stats <teamId>                     # Team card count + trust score

Sources

# List and inspect sources
guru sources list                                          # List all connected sources
guru sources list --fields id,name,definitionName          # Just names and connector types
guru sources get <sourceId>                                # Get a source by ID (sync status, connection info)

# Facet discovery — discover filterable fields from connected systems
guru sources object-types <sourceId>                       # List object types + their facets
guru sources facet-values <sourceId> <facetId>             # List values for a facet
guru sources facet-hierarchy <sourceId> <facetId>          # Root nodes of hierarchical facet
guru sources facet-hierarchy <sourceId> <facetId> <parentId>  # Children of a hierarchy node

# Workflow: discover facets → search with filter
guru sources list --fields id,name,definitionName          # Find sourceId
guru sources object-types <sourceId>                       # Find facetId
guru sources facet-values <sourceId> <facetId>             # Find value
guru search -t "pricing" --facet-field-id <facetId> --facet-value "Enterprise"

Schema Introspection

guru schema                                   # List available resource schemas
guru schema card                              # Get JSON Schema for cards
guru schema cards                             # Also works (plural -> singular normalization)
guru schema Card                              # Also works (case-insensitive)
guru schema folder-item                       # Get JSON Schema for folder items
guru schema collection                        # Get JSON Schema for collections

Auth

guru auth status                              # Validate credentials (shows source: local/env/config-file)
guru auth setup --user <email> --token <token> # Store credentials globally (~/.config/guru-cli/)
guru auth setup --local --user <email> --token <token>  # Store in project (.config/guru-cli/)
guru auth export                              # Show credentials (masked by default)
guru auth export --unmasked                   # Show raw credentials (for scripted / agent use)
guru auth logout                              # Remove global credentials
guru auth logout --local                      # Remove project-scoped credentials

Config

guru config show                              # Show effective config with source for each value
guru config set write-level safe              # Persist write level globally
guru config set write-level all --local       # Persist write level for this project only
guru config set audit-log /var/log/guru.jsonl # Persist audit log path
guru config unset audit-log                   # Remove a setting (reverts to env or default)
guru config unset write-level --local         # Remove a project-scoped setting

Settings are stored separately from credentials. Both global and local scopes are supported:

| Priority | Source | Example | | ----------- | ---------------------------------------------- | ------------------------------------------ | | 1 (highest) | Local .config/guru-cli/settings.json | guru config set write-level safe --local | | 2 | Environment variable / .env | GURU_CLI_WRITE_LEVEL=safe | | 3 | Global ~/.config/guru-cli/settings.json | guru config set write-level safe | | 4 (lowest) | Default | moderate for write-level |

Dry Run

Every command supports --dry-run to validate inputs and preview execution without calling the API:

guru cards get abc123 --dry-run
# -> { "ok": true, "data": { "dryRun": true, "command": "cards get", "args": { "cardId": "abc123" } } }

guru cards create --title "Test" --content "<p>Hi</p>" --collection col123 --dry-run
# -> validates all inputs, shows resolved args, makes no API call

guru search -t "onboarding" --dry-run
# -> shows what would be searched without hitting the API

Agent Workflow Recipes

Typical multi-step workflows an AI agent might run:

# 1. Discover the CLI surface
guru --help                                      # See all commands + resource hierarchy
guru schema                                      # List all resource schemas
guru schema card                                 # Inspect the card data shape

# 2. Search across all knowledge (cards + external sources)
guru search -t "onboarding"                          # Both cards + sources (default)
guru search -t "deploy" --mode sources               # Source-only (dedicated endpoint)
guru search -t "deploy" --mode cards                 # Card-only (dedicated endpoint)

# 3. Find and read a card
guru collections list --fields id,name           # Find a collection
guru folders list --collection "Engineering" --fields title,section  # Browse folders (with sections)
guru folders items "Coding Agents" --collection "Engineering" --type card --fields id,preferredPhrase
guru cards get <cardId> --fields title,content   # Read the card

# 4. Create and tag a card
guru tags list --fields name,tags                # Find tag IDs
guru cards create --title "New Process" --content "<h1>Steps</h1><p>...</p>" --collection <colId> --tags <tagId1>,<tagId2>

# 5. Agent-assisted verification loop (compound engineering)
guru cards unverified --fields id,preferredPhrase   # Find cards needing review
guru cards get <cardId> --fields content            # Read the card
guru cards verify <cardId>                          # Confirm still accurate
# OR: flag an issue and annotate
guru cards add-comment <cardId> --content "Step 3 references Postgres 14, but infra shows Postgres 16"
guru cards unverify <cardId>                        # Mark as stale

# 5b. Comment thread workflow
guru cards comments <cardId> --fields id,content,status  # See existing comments
guru cards reply-comment <cardId> <commentId> --content "Fixed in commit abc123"
guru cards resolve-comment <cardId> <commentId>    # Mark the issue as resolved
guru cards unresolve-comment <cardId> <commentId>  # Reopen if still an issue

# 6. Audit group access
guru groups list --fields id,name                # List groups
guru groups members "Engineering" --fields email,firstName  # Who's in the group?
guru groups collections "Engineering" --fields collectionName,role  # What can they access?

# 7. Provision a new team group
guru groups create --name "Platform Team"        # Create group
guru groups add-members "Platform Team" --emails [email protected],[email protected]  # Add members
guru groups members "Platform Team" --fields email  # Verify membership
guru groups remove-member "Platform Team" [email protected]  # Adjust if needed
guru groups delete "Platform Team"               # Cleanup when done

License

Copyright © Guru Technologies, Inc. Proprietary — see LICENSE.md.