Skip to content

CLI

The g8 CLI gives you terminal access to graph8’s developer tools — get framework-specific tracking snippets and progressive form templates directly from your terminal.

Installation

Terminal window
pip install g8-mcp-server

This installs the g8 command. Requires Python 3.10+.

Authentication

Three ways to authenticate:

Terminal window
g8 login

Opens your browser to sign in via OAuth. Once authenticated, a token is saved to ~/.g8/credentials.json and used automatically for all future commands. No API key needed.

API key

If you prefer using an API key (e.g., for CI/CD or scripts), create one in Settings -> API and either:

Store it locally:

Terminal window
g8 login --api-key

Prompts you to paste an API key, validates it, and saves it to ~/.g8/credentials.json.

Or set it as an environment variable:

Terminal window
export G8_API_KEY="your_api_key_here"

g8 logout

Remove stored credentials:

Terminal window
g8 logout

g8 whoami

Check your current authentication status:

Terminal window
g8 whoami
# Auth source:  OAuth (~/.g8/credentials.json)
# Logged in as: thomas@graph8.com

Commands

g8 snippet

Get the graph8 tracking snippet for any supported framework. The snippet loads p.js — the graph8 tracking script — on every page.

Usage:

Terminal window
# Get snippet for a framework
g8 snippet --framework nextjs


# List all supported frameworks
g8 snippet --list


# Get snippet for a specific repo
g8 snippet --framework react --repo-id <repo-id>


# Output as JSON
g8 snippet --framework html --format json

Options:

OptionDescription
--frameworkTarget framework (required unless --list)
--listList all supported frameworks
--repo-idRepository ID for repo-specific config (optional)
--formatOutput format: text (default) or json

Supported Frameworks:

FrameworkRenderingDescription
htmlSSRHTML / Vanilla JS — script tag in <head>
reactCSRReact — useEffect component
nextjsSSRNext.js — next/script for App Router and Pages Router
vueCSRVue — onMounted composable
wordpressSSRWordPress — functions.php hook
webflowSSRWebflow — Custom Code in project settings
shopifySSRShopify — theme.liquid snippet

Example output:

Terminal window
$ g8 snippet --framework nextjs
============================================================
graph8 Tracking Snippet — Next.js
============================================================


Setup Steps:
  1. App Router: add the Script to app/layout.tsx
  2. Pages Router: add the Script to pages/_app.tsx
  3. Use window.g8?.track() and window.g8?.identify() in client components


Code:
————————————————————————————————————————————————————————————
// app/layout.tsx (App Router)
import Script from 'next/script';


export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <Script
          src="https://t.graph8.com/p.js"
          data-write-key="your-write-key"
          data-tracking-host="https://t.graph8.com"
          strategy="afterInteractive"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}
————————————————————————————————————————————————————————————


Tracking Methods:
  identify: g8.identify("user-id", {email: "user@example.com", name: "Jane Doe"})
  track: g8.track("event_name", {property: "value"})

Privacy Options

The generated snippet includes data-attributes you can add to control privacy behavior:

AttributeValuesDescription
data-privacy-dont-send"true"Disables cookies and event sending
data-privacy-user-ids"true"Disables storing user identifiers
data-privacy-ip-policy"keep", "stripLastOctet", "remove"Controls IP address handling
data-init-only"true"Initializes the script without sending a page event

Verifying the Snippet

After adding the snippet to your app:

  1. Open browser DevTools -> Network tab
  2. Look for requests to your tracking host (/p.js)
  3. In Console: window.g8 should be defined
  4. Call g8.track('test_event') — you should see a network request

g8 form

Get a progressive form template — an embeddable or popup form that collects data in stages across multiple visits.

Usage:

Terminal window
# Get an embedded form template
g8 form --framework react --variant embedded


# Get a popup form template
g8 form --framework nextjs --variant popup


# Custom field stages
g8 form --framework html --variant embedded \
  --stages '[{"stage":1,"fields":[{"name":"email","type":"email","required":true}]}]'


# Output as JSON
g8 form --framework vue --variant popup --format json

Options:

OptionDescription
--frameworkTarget framework (required)
--variantForm variant: embedded or popup (required)
--repo-idRepository ID for repo-specific config (optional)
--stagesCustom field stages as JSON string (optional)
--formatOutput format: text (default) or json

Form Variants:

VariantBest for
embeddedInline forms within page content (signup sections, footers, sidebars)
popupModal/overlay forms triggered by buttons or page events

Progressive Form Stages

Forms collect data progressively across visits — asking for a little more each time. The default stages are:

StageFieldsPurpose
1work_emailInitial capture — lowest friction
2first_name, last_name, companyIdentity enrichment
3job_title, phoneQualification data

The form tracks which stage the visitor has completed using localStorage and shows the next stage on their return visit.

Custom stages: Pass a JSON array to --stages to override the defaults:

Terminal window
g8 form --framework react --variant embedded \
  --stages '[
    {"stage": 1, "fields": [
      {"name": "email", "type": "email", "required": true}
    ]},
    {"stage": 2, "fields": [
      {"name": "name", "type": "text", "required": true},
      {"name": "role", "type": "select", "required": false,
       "options": ["Developer", "Manager", "Executive"]}
    ]}
  ]'

Data Flow

When a form is submitted, the data flows through graph8’s tracking pipeline:

  1. Form captures field values from the visitor
  2. g8.identify() sends the data to graph8’s CDP
  3. g8.track() records the form submission event
  4. Data appears in the contact profile in your graph8 workspace

Output Formats

FormatFlagDescription
Text--format text (default)Human-readable output with headers, code blocks, and setup steps
JSON--format jsonMachine-readable output — same structure as the MCP tool response

The JSON format is useful for piping into other tools or scripts:

Terminal window
g8 snippet --framework html --format json | jq '.snippet_code'

Workflow

The recommended order for integrating graph8 into your app:

  1. Install the tracking snippet — this is always the first step

    Terminal window
    g8 snippet --framework nextjs

  2. Add the snippet to your app — follow the setup steps in the output

  3. Configure tracking — add identify and track calls:

    // On login/signup
    g8.identify("user-123", { email: "user@example.com", name: "Jane" });
    

    // On key actions
    g8.track("plan_selected", { plan: "pro", billing: "annual" });

  4. Add progressive forms — once tracking is working:

    Terminal window
    g8 form --framework nextjs --variant embedded

  5. Verify — open DevTools Network tab and look for requests to your tracking host