{
  "markdown": "# geekbot-cli\n\n[![npm version](https://img.shields.io/npm/v/geekbot-cli)](https://www.npmjs.com/package/geekbot-cli)\n[![CI](https://github.com/geekbot-com/geekbot-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/geekbot-com/geekbot-cli/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n[Geekbot](https://geekbot.com) runs asynchronous standups, check-ins, and polls in Slack and Microsoft Teams. This CLI lets you run them straight from your AI coding agent — or the terminal.\n\nEvery command returns structured JSON with machine-readable exit codes, credentials live in your OS keychain (never in dotfiles), and it works wherever your agent does — Claude Code, Claude Desktop, Codex CLI, Gemini CLI, and any Agent Skills tool (Cursor, Windsurf, Copilot, …).\n\n## 🚀 Quick Start\n\nTwo steps, then you're talking to Geekbot in plain English.\n\n### Step 1 — Add Geekbot to your agent\n\nPick your tool:\n\n<details open>\n<summary><b>Claude Code</b></summary>\n\n```shell\n# Inside Claude Code:\n/plugin marketplace add geekbot-com/geekbot-cli\n/plugin install geekbot@geekbot-cli\n/reload-plugins\n```\n</details>\n\n<details>\n<summary><b>Claude Desktop</b></summary>\n\n1. **Settings → Extensions → Install from GitHub…** and enter `geekbot-com/geekbot-cli`, then restart when prompted.\n2. **Allowlist the API domain.** Claude Desktop sandboxes network access, so add `api.geekbot.com` under **Settings → Sandbox → Allowed domains** and apply it to *all conversations*. (Org admins must also allow it in the Anthropic console.)\n\n> Skills only run in surfaces that support tools — today that's **cowork sessions** and **code chats**, not regular text chats.\n</details>\n\n<details>\n<summary><b>Codex CLI</b></summary>\n\n```shell\n# Register the marketplace (shell):\ncodex plugin marketplace add geekbot-com/geekbot-cli\n```\n\nThen start `codex`, open `/plugins`, find **geekbot** under the `geekbot-cli` marketplace, and install it.\n</details>\n\n<details>\n<summary><b>Gemini CLI</b></summary>\n\n```shell\ngemini extensions new geekbot --from geekbot-com/geekbot-cli\n```\n</details>\n\n<details>\n<summary><b>Cursor, Windsurf, Copilot & 60+ other agents</b></summary>\n\nThese tools don't use plugins — they support the open **Agent Skills** convention (a `SKILL.md` file the agent auto-discovers). Install the Geekbot skill into all of them at once with [Vercel Skills](https://github.com/vercel-labs/skills), which detects your installed agents and copies (or symlinks) the skill into each one's `skills/` directory:\n\n```shell\nnpx skills add geekbot-com/geekbot-cli\n```\n\nThis covers Cursor, Windsurf, GitHub Copilot, Cline, Roo Code, Zed, and [dozens more](https://github.com/vercel-labs/skills#supported-agents).\n</details>\n\n### Step 2 — Ask your agent to set up Geekbot\n\nJust say it in plain English:\n\n> **\"Set up Geekbot.\"**\n\nYour agent will:\n\n1. **Install the `geekbot` CLI** (`npm install -g geekbot-cli`) if it isn't already on your `$PATH`.\n2. **Log you in** — browser-based OAuth, no API key to paste. The token is stored securely in your OS keychain.\n3. **Verify everything** and report back.\n\nThat's it. Now just ask for what you want:\n\n> *\"Fetch my standups.\"*\n> *\"Draft my standup report for today.\"*\n> *\"Who hasn't posted in the daily standup?\"*\n> *\"Create a poll asking the team where to go for lunch.\"*\n\n---\n\n### Not using an AI agent?\n\nYou can drive the CLI directly. See [Manual installation](#manual-installation) below.\n\n```shell\nnpm install -g geekbot-cli   # install\ngeekbot auth login           # browser OAuth (or: geekbot auth setup --api-key <KEY>)\ngeekbot standup list         # structured JSON on stdout\n```\n\n---\n\n### Keeping Geekbot up to date\n\nPlugin updates are **pull-based** — when a new version ships, your agent won't pick it up on its own (auto-update is off by default for third-party marketplaces). Refresh it yourself:\n\n<details open>\n<summary><b>Claude Code</b></summary>\n\n```shell\n# Inside Claude Code:\n/plugin marketplace update geekbot-cli\n/reload-plugins\n```\n\nOr turn on auto-update once: run `/plugin` → **Marketplaces** → select `geekbot-cli` → **Enable auto-update**. Claude Code then refreshes after each session starts.\n</details>\n\n<details>\n<summary><b>Codex CLI</b></summary>\n\n```shell\n# Refresh the marketplace snapshot, then re-install to pick up the new version:\ncodex plugin marketplace upgrade geekbot-cli\ncodex plugin add geekbot@geekbot-cli\n```\n</details>\n\n> The `geekbot` CLI binary updates independently of the plugin: `npm install -g geekbot-cli@latest` (or `bun install -g geekbot-cli`).\n\n---\n\n## 🛠️ Commands\n\nThe CLI follows a `geekbot <resource> <action> [options]` pattern. Run `geekbot <resource> <action> --help` for the full option list on any command. It wraps the Geekbot API — see [developers.geekbot.com](https://developers.geekbot.com) for the underlying endpoints and full data shapes.\n\n| Resource | Actions | What it does |\n|----------|---------|--------------|\n| `standup` | `list` · `get <id>` · `participation <id>` · `create` · `start <id>` | List, inspect, create, trigger standups, or read participation |\n| `report` | `list` · `get <id>` · `create` · `edit <id>` · `delete <id>` | Read and submit standup reports |\n| `poll` | `list` · `get <id>` · `votes <id>` · `participation <id>` · `create` | Manage polls, read results and response rate *(Slack teams only)* |\n| `me` | `show` · `teams` | Show your profile or the teams you belong to |\n| `team` | `list` | List teams with their members |\n| `auth` | `login` · `setup` · `status` · `remove` | Manage authentication (see below) |\n\nA few common examples:\n\n```shell\ngeekbot standup list\ngeekbot standup create --name \"Sprint Retro\" --channel \"#engineering\" \\\n  --questions '[\"What went well?\",\"What could improve?\"]'\ngeekbot standup participation 123 --since 2026-01-01 --until 2026-02-01\ngeekbot report create --standup-id 123 --answers '{\"101\":\"Shipped auth\",\"102\":\"Writing tests\"}'\ngeekbot poll create --name \"Lunch\" --channel \"#general\" \\\n  --question \"Where to?\" --choices '[\"Pizza\",\"Sushi\",\"Tacos\"]'\ngeekbot poll participation 456\n```\n\n## 🔑 Authentication\n\nThe CLI resolves credentials from the first source it finds, in this order:\n\n1. **`--api-key <key>`** — per-command override, handy for scripts and CI\n2. **`GEEKBOT_API_KEY`** environment variable — session/shell-level credential\n3. **OS keychain** — persistent, secure storage written by `geekbot auth login` or `geekbot auth setup`\n\n**OAuth (`geekbot auth login`) is the preferred way to sign in** — a quick browser approval that stores a short-lived, revocable token in your OS keychain and never exposes a secret in your terminal. The API key is an alternative for cases where OAuth isn't an option, such as CI or headless environments.\n\n### OAuth login (recommended)\n\n```shell\ngeekbot auth login\n```\n\nRuns the OAuth 2.0 authorization-code flow with PKCE: opens your browser, you approve in the Geekbot dashboard, and a short-lived `cli_*` token is written to your OS keychain — nothing is pasted into your terminal or shell history.\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `--no-browser` | — | Print the authorize URL instead of launching a browser (use on WSL, SSH, or headless boxes) |\n| `--device-name <name>` | hostname | Friendly name shown on the token in the dashboard, so you can revoke it later |\n| `--ttl-days <days>` | `30` | Token lifetime. Allowed: `7`, `30`, `90`, `180`, `365` |\n\n### API-key setup (alternative)\n\nHandy for CI or where OAuth isn't available. Grab a key at <https://app.geekbot.com/dashboard/api-webhooks>.\n\n```shell\ngeekbot auth setup --api-key <YOUR_KEY>   # or run `geekbot auth setup` to enter it interactively\n```\n\nThe key is validated against the API before being stored in your OS keychain (macOS Keychain, Windows Credential Vault, or Linux Secret Service) — never on disk in plaintext.\n\n### Manage credentials\n\n```shell\ngeekbot auth status     # verify stored credentials work\ngeekbot auth remove     # delete the stored key from the keychain\n```\n\n## 🔒 Privacy\n\n- **The CLI talks only to Geekbot.** Network requests go to `api.geekbot.com` (and `oauth.geekbot.com` during login).\n- **Credentials never leave your machine** except to authenticate with Geekbot.\n- **Command output is your team's data** — standups, reports, poll votes. When you run the CLI through an AI agent, that output enters the agent's context and may be sent to the model provider. Keep that in mind for anything sensitive.\n\n## 📦 Output format\n\nEvery command writes a JSON envelope to **stdout**; diagnostics (help, parse errors) go to **stderr**.\n\n```json\n{\n  \"ok\": true,\n  \"data\": { \"id\": 123, \"name\": \"Daily Standup\", \"channel\": \"#engineering\" },\n  \"error\": null,\n  \"metadata\": { \"timestamp\": \"2026-03-17T10:30:00.000Z\" }\n}\n```\n\nOn failure, `ok` is `false` and `error` carries machine-readable fields — including a `retryable` flag and an actionable `suggestion`:\n\n```json\n{\n  \"ok\": false,\n  \"data\": null,\n  \"error\": {\n    \"code\": \"standup_not_found\",\n    \"message\": \"Standup 999 not found\",\n    \"retryable\": false,\n    \"suggestion\": \"Run `geekbot standup list` to see available standups.\"\n  },\n  \"metadata\": { \"timestamp\": \"2026-03-17T10:30:00.000Z\" }\n}\n```\n\nEach error class maps to a distinct exit code, so scripts can branch without parsing text:\n\n| Code | Name | Meaning |\n|------|------|---------|\n| 0 | `SUCCESS` | Completed successfully |\n| 1 | `GENERAL` | Unexpected / unclassified error |\n| 2 | `USAGE` | Invalid syntax or missing required options |\n| 3 | `NOT_FOUND` | Resource does not exist |\n| 4 | `AUTH` | Authentication failed (missing or invalid key) |\n| 5 | `FORBIDDEN` | Insufficient permissions |\n| 6 | `VALIDATION` | Input validation failed |\n| 7 | `NETWORK` | Network error (DNS, timeout, connection refused) |\n| 8 | `CONFLICT` | Resource conflict (duplicate, concurrent change) |\n| 9 | `API_ERROR` | Geekbot API returned an unexpected error |\n\n## 🩺 Troubleshooting\n\n| Symptom | Fix |\n|---------|-----|\n| **`geekbot: command not found`** after install | The global bin isn't on your `$PATH`. Reopen your shell, or check `npm bin -g` / `bun pm bin -g` and add it to `$PATH`. |\n| **`npx geekbot-cli` fails** with a shebang/`bun` error | The CLI uses a `#!/usr/bin/env bun` shebang — `npx` is *not* a Node fallback. Install globally (`npm install -g geekbot-cli`) and run `geekbot`, or put Bun ≥ 1.3.5 on your `$PATH`. |\n| **Browser doesn't open on `auth login`** (WSL, SSH, headless) | Run `geekbot auth login --no-browser` and open the printed URL manually. |\n| **Calls fail in Claude Desktop** with a network error | Allowlist `api.geekbot.com` under **Settings → Sandbox → Allowed domains** (apply to all conversations). Org admins must also allow it in the Anthropic console. |\n| **`auth status` reports not authenticated** | Re-run `geekbot auth login`, or confirm `GEEKBOT_API_KEY` isn't set to a stale value (env vars override the keychain). |\n\n## 💬 What you can ask for\n\nNew to Geekbot, or not sure what's possible? Once it's set up, here are the kinds of things you can ask your agent in plain English — it picks the right commands for you.\n\n**Standups** — recurring async check-ins where teammates answer a few questions on a schedule.\n- *\"What standups am I in?\"*\n- *\"Set up a daily standup for #engineering at 10am asking what people did yesterday and what's planned today.\"*\n- *\"Trigger the daily standup now.\"*\n\n**Reports** — the answers people submit to a standup.\n- *\"Draft my standup report for today.\"*\n- *\"Did everyone post in today's standup? Who's missing?\"*\n- *\"Summarize this week's reports — what are the blockers?\"*\n\n**Polls** *(Slack teams only)* — quick team votes.\n- *\"Create a poll asking where we should go for the team lunch.\"*\n- *\"Show me the results of the lunch poll.\"*\n\n**Team & profile**\n- *\"Who's on my team?\"*\n- *\"Show my Geekbot profile.\"*\n\n## 🤝 Contributing\n\nContributions are welcome! To get set up:\n\n```shell\ngit clone https://github.com/geekbot-com/geekbot-cli.git\ncd geekbot-cli\nbun install\nbun test          # run the suite\nbun run check     # lint + format\n```\n\nThen:\n\n1. Fork the repo and create a feature branch (`git checkout -b my-feature`).\n2. Make your changes and add tests.\n3. Run `bun test` and `bun run check` to verify.\n4. Open a pull request against `main`.\n\nFound a bug or have an idea? [Open an issue](https://github.com/geekbot-com/geekbot-cli/issues).\n\nMaintainers: see [RELEASING.md](RELEASING.md) for how the npm CLI and the agent plugin are versioned and published — they're two separate release lines.\n\n## 📄 License\n\n[MIT](LICENSE) © Geekbot\n",
  "bytes": 12611,
  "sha": "1bec233b4a69c3246b793c9f03f5471531ea36485cee44625939447bf24f9502",
  "repo_slug": "geekbot-com/geekbot-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_geekbot_com_geekbot_cli_bd6f1060/readme"
}