aiguru — Guru AI developer CLI

An agentic terminal companion for your codebase, models, and MCPs. Ask questions, review and test code, scaffold clean projects, and run tool-using tasks — all from the terminal, powered by self-hosted Guru AI models (no OpenAI bill, data stays on your infra).

npm install -g aiguru      # install / update
aiguru                     # launch the interactive assistant

Quick start

aiguru login                       # sign in (API key or email + password)
aiguru ask "how does auth work here?"
aiguru review src/                 # AI code review with fixes
aiguru new myapp --template flutter-firebase   # instant scaffold
aiguru task "summarize these files" --mcp filesystem --dir .

Every answer shows token usage; reports always include a fix, not just criticism.

Model tiers

Pick a tier on any command with --high / --pro / --low (default: aiguru-pro):

| Tier | Flag | Backed by | Use for | |------|------|-----------|---------| | Pro (default) | --pro | Qwen2.5-Coder 14B | balanced day-to-day | | High | --high | Qwen2.5-Coder 32B | hard reasoning, large scaffolds | | Low | --low | DeepSeek-Coder-V2 16B | fast / economy |

All are self-hosted on GPU and metered per tier — see aiguru usage.

Models

Guru ships three self-hosted tiers, or bring your own key — you never type a model id, the CLI picks the best model your key has access to.

aiguru model            # numbered list; pick 1-6, paste a key if needed
aiguru model use high   # or: 3, claude, gemini, openai

| # | Model | Notes | |---|-------|-------| | 1 | Guru Pro | balanced, self-hosted (default) | | 2 | Guru High | max quality, self-hosted | | 3 | Guru Low | fast, self-hosted | | 4 | OpenAI | your key — picks GPT-5.6 class | | 5 | Gemini | your key — picks gemini-3.5-flash class | | 6 | Claude | your key — picks Opus 4.8 class |

In the REPL: /model opens the same chooser; the active model shows on the prompt.

Where your key is saved

After a key validates, the CLI asks where to keep it:

| Choice | Stored | Notes | |--------|--------|-------| | This machine only | ~/.guru/config.json (chmod 600) | Never leaves the box, works offline | | My Guru account | Encrypted on the backend | Shows in the web dashboard, syncs to every machine you sign in from |

aiguru model where          # what's saved, and where
aiguru model sync           # pull account keys onto this machine (runs on login too)
aiguru model push openai    # promote a machine-only key to your account
aiguru model remove openai  # delete it (account copy too, if that's where it lives)

Signing out clears account-scoped keys from the machine; local-only keys stay put. On the web: Settings → Model Keys.

Commands

Sign in & account

aiguru login                 # menu: API key OR email + password (key validated before saving)
aiguru login --key guru_key_...        # non-interactive
aiguru login --email [email protected] --password ***    # scripted
aiguru whoami                # current account
aiguru logout                # sign out
aiguru config                # show settings (key masked)
aiguru usage                 # token usage, broken down per model tier

Ask & understand your code

aiguru ask "question"        # ask the model anything
aiguru review <file|dir>     # code review: issues + a fix for each + verdict
aiguru explain <file|dir>    # explain what the code does
aiguru arch [dir]            # size the project + recommend a matching architecture (MVC → DDD)
aiguru chat "prompt"         # low-level direct model call (advanced)

Test everything

aiguru tester api  <url>     # endpoint test + report + suggested cases
aiguru tester ui   <url>     # structure / a11y report
aiguru tester code <path>    # bugs + fixes + test plan  (auto-detects language & framework)
aiguru tester code <path> --write     # actually CREATE the test files (asks first)
aiguru tester function <path>
aiguru test-api <url> [--method GET] [--body '..'] [--auth]

Reports save a timestamped color PDF to ./guru-reports/ (use --no-pdf to skip, --out <dir> to redirect).

Create new — asks before writing, never touches an existing project

aiguru templates             # list ready-made starters (instant, offline, no tokens)
aiguru new <name> --template flutter-firebase     # scaffold from a template
aiguru new                   # guided wizard: type → framework → size → features
aiguru new <name> --type <backend|api|mobile|web> --advise    # recommend a stack, then scaffold
aiguru new <mvc|ddd|clean|hexagonal|layered> <name>           # pick the pattern yourself
aiguru feature add <name>    # add a feature module (auto-detects Flutter/Node), DDD layers

Options: --framework · --lang · --size <small|medium|large|mega> · --features "auth,billing" · --about "..." · --dir . · --dry (recommend only).

Ready templates: flutter-ddd, flutter-firebase, node-express-ddd. Scaffolding into an existing non-empty folder is refused by design.

Do tasks with tools (MCP)

aiguru task "..." --mcp filesystem --dir <path>   # agent uses tools to do the task
aiguru task "..." --mcp postgres                  # needs DATABASE_URL (self-signed: sslmode=no-verify)
aiguru task "..." --mcp mock                       # bundled demo tools, no setup

aiguru mcp install <name> [--stdio "cmd args" | --url <endpoint>]   # install (syncs to your account)
aiguru mcp installed         # MCPs installed to your account (visible on the web dashboard)
aiguru mcp connected         # connectable servers (built-ins + local)
aiguru mcp tools <name>      # show a server's tools
aiguru mcp remove <name>

Built-in servers: filesystem, postgres, mock. Add any remote / OAuth MCP (e.g. Google) with aiguru mcp install google --url <endpoint> --header "Authorization: Bearer <token>" after you complete its OAuth.

Marketplace, platform & local

aiguru mcp list|info <n>|test <n>|health   # browse the MCP marketplace
aiguru agents | connections | reports | health
aiguru ls [dir]              # project tree (no model)
aiguru read <file>           # print a file (no model)
aiguru theme [name]          # guru · ocean · sunset · forest · mono
aiguru update                # update to the latest version

Interactive session (aiguru with no args)

Slash commands: /review /explain /arch /tester code|function /model <name> /theme <name> /login /clear /help /exit.

Flags reference

| Flag | Meaning | |------|---------| | --high --pro --low | model tier (also --model <name>) | | --dry | preview / recommend without calling or writing | | --write | (tester) create the test files | | --pdf / --no-pdf / --out <dir> | report PDF control | | --mcp a,b --dir --db-url | MCP task options | | --type --framework --lang --pattern --size --features --about | scaffold options | | --auth --method --body | HTTP test options | | --key --email --password | scripted login |

Capabilities

• Three self-hosted model tiers, routed by flag, metered per tier.
• Agentic MCP tool-use — connect local (stdio) or remote (HTTP/OAuth) MCP servers and let the model do things.
• Instant template scaffolding — deterministic, offline, no tokens; plus a model-driven new that recommends a stack and scales folders to size + feature count.
• feature add — drop a new DDD feature module into a new or existing project (never overwrites).
• Stack-aware testing — detects language + test framework; --write creates real test files.
• Scale-matched architecture advice — arch recommends MVC → DDD to fit the project's size.
• Color PDF reports — timestamped, saved locally.
• Themes — 5 built-in, persisted; honors NO_COLOR.
• Safe by default — validates keys before saving, asks before writing files, 401 auto-recovery, and clear offline / quota / rate-limit / context-too-large messages.

Config & environment

• Config file: ~/.guru/config.json
• MCP servers: ~/.guru/mcp.json
• Env overrides: GURU_API_URL, GURU_API_KEY, GURU_MODEL_URL, GURU_MODEL_KEY, GURU_MODEL, GURU_THEME, NO_COLOR

Run aiguru help for the full list.

MIT · © Guru AI