CLI FAQ

Common questions about the g8 CLI — graph8’s terminal client. If your question isn’t here, see the CLI overview or CLI Examples.

Install and update

How do I install it?

pip install g8-mcp-server

This installs the g8 command. Requires Python 3.10+. The same package also ships the MCP server — 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?

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:

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?

g8 login (recommended) — OAuth in browser, saves token to ~/.g8/credentials.json.
g8 login --api-key — paste a key, validates + saves to the same file.
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.

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/js/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.

Always free on both paid plans (within the 5 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 5 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:

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:

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:

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 5 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. 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.