# CLI FAQ

> Common questions about the g8 CLI — install, auth, scripting, output formats, parity with MCP and SDK

Source: https://docs.graph8.com/developers/cli-faq/

Common questions about the `g8` CLI — graph8's terminal client. If your question isn't here, see the [CLI overview](https://docs.graph8.com/developers/cli/) or [CLI Examples](https://docs.graph8.com/developers/cli-examples/).

> **Tip:**
> Try the developer tier free - 1,000 credits, no card required. [Get started](https://auth.graph8.com/en/signup).

## Install and update

### How do I install it?

```bash
pip install g8-mcp-server
```

This installs the `g8` command. Requires Python 3.10+. The same package also ships the [MCP server](https://docs.graph8.com/developers/mcp/) — installing it once gives you both surfaces.

### Why is the package named `g8-mcp-server` if I just want the CLI?

The MCP server and CLI share the same client and ~80% of the same handler code. Splitting them into separate packages would mean two copies of the API client, two upgrade paths, and two installs to keep in sync. One package = one upgrade.

### How do I upgrade?

```bash
pip install --upgrade g8-mcp-server
```

Run `g8 --help` after upgrading to confirm the version banner shifted.

### Can I run it without installing?

Yes — `uvx` runs from PyPI without a permanent install:

```bash
uvx --from g8-mcp-server g8 whoami
uvx --from g8-mcp-server g8 search-contacts --limit 5
```

Slower per-invocation but useful for CI and one-shots.

## Auth

### What are the three ways to authenticate?

1. **`g8 login`** (recommended) — OAuth in browser, saves token to `~/.g8/credentials.json`.
2. **`g8 login --api-key`** — paste a key, validates + saves to the same file.
3. **`G8_API_KEY` env var** — overrides any stored credentials for the current shell. Useful in CI.

### Personal vs org API key?

| Use case | Where | Scope |
|---|---|---|
| Your laptop, scripting your own org | **Profile -> Developer** (personal) | Your user inside the active org |
| Shared service account / production automation | **Settings -> API** (org, admin only) | Whole org |

Most users want the personal key. See [Authentication](https://docs.graph8.com/developers/authentication/).

### What does `g8 whoami` show?

The auth source, the masked API key, the API URL, and (for OAuth) the logged-in email. Use it to verify the CLI is talking to the right org before running write operations.

```
Auth source:  OAuth (~/.g8/credentials.json)
API key:      sk_abcd...wxyz
Logged in as: jane@company.com
API URL:      https://be.graph8.com
```

### How do I switch orgs?

The personal key is scoped to your **active org** at the time the key was issued. To work against a different org, switch orgs in the graph8 app, then re-issue a key from **Profile -> Developer** of that org. Alternatively, use a different `G8_API_KEY` env var per shell.

## Parity, credits, and rate limits

### Does the CLI have everything MCP has?

Functionally yes for server-side operations — **141 commands** across CRM, prospecting, sequences, inbox, deals, tasks, notes, fields, audience + CRM sync, campaigns, quotes, stage pipelines, workflows, skills, voice, intent, and studio. Browser-only widgets (`copilot`, `chat`, `calendar`) and AI agent discovery (`g8_tool_search`) intentionally aren't in the CLI.

### Does the CLI have everything the SDK has?

Nearly. The CLI omits:

- The browser widgets (`copilot`, `chat`, `calendar`, `forms`) — terminals can't render UI.
- The React adapter and `useG8` hook (`@graph8/sdk/react`).

Otherwise, every server-side SDK module has a corresponding CLI command group.

### What costs credits?

Mental model: **graph8-owned data is free on both plans. Third-party data, AI, voice, sends, and meeting bookings charge credits on both plans.** Full matrix in [Pricing](https://docs.graph8.com/developers/pricing/).

**Always free on both paid plans (within the 50 rps cap):**

graph8-owned data:

- `g8 find-contacts`, `find-companies` — B2B index search
- `g8 lookup-person`, `lookup-company` — index lookups
- `g8 build-list` (search + save)
- `g8 intent-stats`, `intent-list-keywords`, `intent-page-visitors`, etc. — intent + visitor reads

First-party CRM + metadata:

- `g8 search-contacts`, `create-contact`, `list-deals`, `create-task`, `list-notes` and all CRM CRUD
- `g8 workflow-list`, `skill-create-llm`, `list-stage-pipelines` and all metadata CRUD
- `g8 studio-icps`, `studio-personas`, `studio-global-context`, etc.
- `g8 snippet`, `g8 form` — template generation

**Always charges credits (both plans):**

- `g8 inbox-draft` — per LLM tokens
- `g8 enrich` (3rd-party waterfall) — 0.5-20 per provider hit (Prospeo, Apollo, Hunter, Cognism, Kickbox, ZeroBounce, etc.)
- `g8 add-to-sequence` and any sequencer/campaign send — 1 cr / step
- Newsletter / nurture send — 1 cr / recipient
- Voice operations — 20 cr / minute of call audio
- **Meeting bookings** — 20 cr flat per confirmed booking
- `g8 skill-execute` with `type=llm` — per LLM tokens
- Audience-sync triggers — per record where the destination platform meters

Note: Copilot (chat / `g8.copilot.ask`) charges per LLM tokens — but Copilot is a browser/SDK widget; the CLI doesn't expose it directly.

*If you stay on graph8-owned data and CRUD on records you already own, you spend zero credits on either plan.*

### Are CLI calls rate-limited?

Yes — the standard 50 rps per-org cap applies. If you script through `xargs` or `parallel`, throttle accordingly.

## Output and scripting

### What's the output format?

Every command outputs **JSON to stdout**. Errors go to stderr with a non-zero exit code. That makes everything pipe-friendly:

```bash
g8 search-contacts --job-title "VP" --limit 50 | jq '.[].work_email'
g8 list-deals --stage-id stg_proposal | jq 'length'
```

### How do I export to CSV?

Use `jq` to project fields, then `@csv`:

```bash
g8 search-contacts --seniority VP --limit 100 \
  | jq -r '.[] | [.first_name,.last_name,.work_email,.job_title] | @csv' \
  > vps.csv
```

### How do I stop on errors in a pipeline?

The CLI exits non-zero on any error (auth, 4xx, 5xx). Combine with shell strictness:

```bash
set -euo pipefail
g8 lookup-person --email jane@acme.com | jq -r '.work_email'
```

### Can I use it in CI?

Yes. Set `G8_API_KEY` in your CI secrets, then call `g8 <cmd>` directly. No login flow needed.

## Common errors

### `Error: No API key — run \`g8 login\` or set G8_API_KEY`

You're not authenticated. Run `g8 login` (or set the env var) and try again.

### `Error: 401 Invalid API key`

The key is wrong, revoked, or scoped to a different org. Run `g8 whoami` to see what's stored.

### `Error: 402 Payment Required`

Out of credits on PAYG. Top up at **Settings -> Billing**.

### `Error: 429 Too Many Requests`

You exceeded 50 rps. Slow down or batch.

### `command not found: g8`

Either pip install didn't put the binary on your `PATH`, or you're using a different Python. Try `python -m g8_mcp_server.cli whoami` to confirm the package is installed, then check `pip show g8-mcp-server` for the install location.

## Migration

### Coming from a custom shell script that hits `/api/v1` directly?

Most one-liners translate 1:1 — see [CLI Examples](https://docs.graph8.com/developers/cli-examples/). The CLI handles auth header injection, pagination defaults, and JSON pretty-printing, so most scripts get shorter.

### Coming from an older `g8` CLI release?

Phase 4 (this release) added 100+ new commands across deals, tasks, notes, fields, quotes, stage pipelines, workflows, skills, voice extras, intent, and studio. Nothing was removed — old commands still work the same. Run `g8 --help` to see the full epilog.

## See also

- [CLI overview](https://docs.graph8.com/developers/cli/) — full command reference
- [CLI Examples](https://docs.graph8.com/developers/cli-examples/) — worked terminal workflows
- [MCP FAQ](https://docs.graph8.com/developers/mcp-faq/) — same answers from the MCP angle
- [SDK FAQ](https://docs.graph8.com/developers/sdk-faq/) — same answers from the JS SDK angle
- [Pricing](https://docs.graph8.com/developers/pricing/) — credit costs and plan comparison