GEOly CLI

The GEOly command-line interface — for people and their agents.

GEOly tracks how brands are mentioned and cited across AI engines (ChatGPT, Google AI Mode, Google AI Overview, Gemini, Copilot). The CLI works like gh: you sign in once, the credential stays on your machine, and the agent you already use (Claude Code, Codex, Cursor…) runs geoly commands on your behalf — it never sees a key.

• geoly run "<question>" — hand a whole question to GEOly's hosted GEO agent; get a receipt.
• geoly call <tool> — one raw data tool, JSON out. Same tools, metrics and OAuth as the MCP server.
• geoly — an interactive chat agent in your terminal, for when you want to dig in yourself.

Install

macOS / Linux

curl -fsSL https://geoly.ai/install.sh | sh

Windows (PowerShell)

irm https://geoly.ai/install.ps1 | iex

Self-contained single binary (no Node, no Python, no sudo — installs to ~/.local/bin). Targets: macOS (arm64/x64), Linux (x64/arm64), Windows (x64). Released binaries update themselves in the background once a day (turn off with GEOLY_NO_AUTO_UPDATE=1; always off in CI); geoly upgrade updates right away.

Mirror (identical scripts, straight from this repo): curl -fsSL https://raw.githubusercontent.com/geoly-ai/GEOly-Cli/main/install.sh | sh · Windows: irm https://raw.githubusercontent.com/geoly-ai/GEOly-Cli/main/install.ps1 | iex

Quick start

# Sign in and teach the agent hosts on this machine (Claude Code / Codex / Cursor) about GEOly
geoly init

# Ask the hosted GEO agent — one JSON receipt on stdout, progress on stderr
geoly run "how did our ChatGPT visibility move this week?" --brand br_123

# Raw data: discover, inspect, call
geoly tools --json
geoly schema get_brand_overview
geoly call get_brand_overview --time_range 30d

# Both credit pools
geoly credits

Signing in. Any command that needs credentials opens your browser once and continues (geoly auth login does it explicitly). No browser on this machine (SSH, a container)? geoly auth login --remote prints a sign-in URL to open anywhere; the page shows a code you paste back with geoly auth login --code <code> — this is picked automatically over SSH, in CI and without a display. Servers and CI use a token instead:

export GEOLY_TOKEN=geom_xxxxxxxx   # server / CI — never triggers a browser

Calling the HTTP API from your own code. After signing in, geoly auth token prints the current access token (a secret) for Authorization: Bearer … on the Agent API and MCP endpoints:

curl -H "Authorization: Bearer $(geoly auth token)"   "https://app.geoly.ai/api/agent/runs?limit=5&org_id=<org_id>"

Long runs. geoly run follows a run for up to 100 s. If it is still going, the command exits 0 with {"status":"running","run_id":…,"next":"geoly runs wait …"} — the run keeps going on the server; run the next command to pick it up. The full receipt is also written to ./.geoly/runs/<run_id>.json (add .geoly/ to your .gitignore). Re-running the exact same command within 10 minutes replays the same run instead of paying for a new one.

Read stopped, not only status. A run that hit its --max-credits cap comes back status: done, stopped: max_steps, stopped_reason: budget with a placeholder answer — nothing failed, so the exit code is 0, but the CLI says on stderr that the answer is partial.

Built for agents

• Stable contract: flags, output behavior, and exit codes are the stable surface. Tool names and schemas come from the server at runtime — check geoly tools --json before calling; the server can add tools without a CLI release.

• stdout is data, stderr is status: results are JSON on stdout (pretty in a TTY, compact when piped). --error-format json emits machine-readable error objects (kind, status, retryAfter, hint).

• Exit codes (geoly <command> --help prints the same table):

  0  ok (a `running` hand-off from `geoly run` is also 0 — it is not a failure)
  1  tool / run error — the server answered, the operation itself failed
  2  usage error — bad flags or parameters; nothing was sent
  3  auth — no valid credentials (run `geoly auth login`)
  4  rate limited — honor `retryAfter` before retrying
  5  subscription required — the organization has no active plan
  6  upstream unavailable or timed out (kind `timeout`) — network / gateway trouble, or no answer within the deadline; a short back-off then one retry is reasonable
  7  credits exhausted — this period's credits are used up
  

• Help is plain text when piped (geoly --help | cat), so agents can read it.

• Old tool names point to the new ones. Tools merged away in the 2026-09-29 consolidation (e.g. get_url_reference_detail, compare_public_brands) fail with exit 2 and a hint with the replacement call — geoly call get_url_detail --window_caliber rolling …. The built-in agent (geoly) maps them the same way.

• Writes need a go-ahead. archive_prompt, update_prompt_tags, move_prompts_to_topic, create_prompt / create_topic / create_competitor and trigger_prompt (spends credits) only run after a [y/N] in a terminal or --yes in a script; the agent session asks the same way (--allow-writes for ask). They appear in your tool list only when the consent screen granted Write on that resource for ONE organization — geoly whoami shows writeTools, and a write tool you were not granted fails with grant_missing and the re-login hint.

• Skills, installed for you. writes the GEOly into every agent host it finds (, , ), fetching the current copy from app.geoly.ai; refreshes it, and released binaries bring it up to date in the background whenever app.geoly.ai publishes a newer one. Offline, the copy embedded in the binary never overwrites a newer skill already installed.

Also available: remote MCP + Skill

The CLI, the MCP server, and the skill share one tool surface and one OAuth. If you prefer a zero-install setup (Claude Desktop, Cowork, Codex, cloud agents), connect the remote MCP:

{
  "mcpServers": {
    "geoly": {
      "type": "http",
      "url": "https://app.geoly.ai/api/mcp/v1"
    }
  }
}

/api/mcp/v1 is the versioned address of GEOly MCP v1; the unversioned /api/mcp serves the same thing and stays available for existing configs. A breaking change would ship as /api/mcp/v2 alongside, with v1 left as is.

Codex users can install the plugin (MCP + skill) from geoly-ai/codex-plugins.

License

FSL-1.1-Apache-2.0 — source-available; each release converts to Apache-2.0 two years after publication.

---

www.geoly.ai · Remote MCP docs · © GEOly