Your First Gremlin Run

10 minutes to your first successful read.

Fast Path (AI-Assisted)

Paste this prompt into Claude Code or another AI coding agent to install, authenticate, and load CRM safety skills in one go.

Loading your setup prompt...

Install g-gremlin

Install the CLI with pipx. Requires Python 3.11+.

# Mac/Linux
PY=python3
$PY -c 'import sys; exit(0 if sys.version_info >= (3,11) else 1)' || PY=python3.11
command -v pipx || $PY -m pip install --user pipx
$PY -m pipx ensurepath
$PY -m pipx install --force "g-gremlin==0.1.19"
$PY -m pipx list

# Windows
python --version
if (-not (Get-Command pipx -ErrorAction SilentlyContinue)) { python -m pip install --user pipx }
python -m pipx ensurepath
python -m pipx install --force "g-gremlin==0.1.19"
python -m pipx list

Restart your shell, then run g-gremlin --version. If not found, run python -m pipx ensurepath (or $PY -m pipx ensurepath on Mac/Linux) and restart your terminal.

Authenticate

Start browser auth (no token paste needed). Use --token only if your environment blocks browser flow.

# Recommended
g-gremlin auth login

# Fallback (if browser flow is blocked)
g-gremlin auth login --token <your-token>

The CLI caches your license locally and refreshes automatically. You only need to authenticate once.

Install CRM safety skills

Load the Gremlin skills before your agent touches Salesforce, HubSpot, or other CRM systems.

npx skills add --all mikeheilmann1024/foundryops-ai --yes

In Claude Code, this installs the published Gremlin skills pack directly. In other AI coding agents, open mikeheilmann1024/foundryops-ai and load the files under skills/ using that agent's native instructions before continuing.

Connect integrations

Connect the systems you selected above. Skip any you don't use.

Salesforce

sf org login web --alias myorg
g-gremlin sfdc connect --target myorg

Requires the Salesforce CLI (sf).

Google Sheets

# Ensure ~/.g_gremlin/credentials.json exists (or set G_GREMLIN_CREDENTIALS)
g-gremlin pull SHEET_ID --range A1:A1 --output .g_gremlin/google_oauth_probe.csv

The first Google command opens a browser for OAuth login. If no browser opens, run the same command in Terminal.app and complete consent there.

HubSpot

HubSpot OAuth (Recommended)

Checking...

Non-technical users should click connect and authorize in the browser. Keep PAT flow only as advanced fallback.

If OAuth is blocked in a sandboxed AI environment, run live checks in local terminal:nslookup api.hubapi.com

CLI OAuth option: g-gremlin hubspot oauth connect. Advanced fallback (PAT only): g-gremlin hubspot connect --access-token <pat-na1-...>. Do not use g-gremlin auth set hubspot.

Verify

Run status and doctor commands to confirm everything is connected.

g-gremlin auth status
# If you connected HubSpot, verify OAuth + identity:
g-gremlin hubspot oauth status --json
g-gremlin hubspot whoami

g-gremlin doctor

Use g-gremlin doctor --format json for machine-readable output. Add --sfdc to include Salesforce connectivity checks.

Guided First Task

Prove your setup works with a safe, read-only operation.

Salesforce: Schema Snapshot

List your org's objects and inspect one.

# List objects in your org
g-gremlin sfdc schema ls

# Inspect a specific object
g-gremlin sfdc schema describe Account

# Export as JSON
g-gremlin sfdc schema describe Account --format json > account_schema.json

Google Sheets: Pull a Range

Read data from any spreadsheet.

# Pull a sample range (replace SHEET_ID with your sheet's ID)
g-gremlin pull SHEET_ID --range "Sheet1!A1:D10" --output output.csv

# Validate the output
g-gremlin validate --csv output.csv

HubSpot: Object Inventory

List your portal's object types.

# List all object types
g-gremlin hubspot schema ls

# Pull a sample of contacts
g-gremlin hubspot pull contacts --properties email,firstname,lastname --limit 5

No integrations: Command Index

Explore what's available.

# Full command index (great for AI agents)
g-gremlin help --json --full

# Detailed help for any command
g-gremlin help enrich

Pro Tips

Run g-gremlin help <command> --json before using any command for the first time - your AI agent can parse the schema.
Use --dry-run or --format json for safe, parseable output.
Run g-gremlin doctor as your first troubleshooting step.
If HubSpot checks fail in an AI/sandbox environment, retry from your local terminal first.
For Salesforce updates, always use sfdc preview-push first to review changes.

What's Next?

See Real Workflows

Step-by-step playbooks for common GTM scenarios.

View Playbooks ->

Full Command Reference

Every Gremlin command with examples.

CLI Reference ->

Get Help

Email [email protected] or check the docs.

Run Diagnostics

g-gremlin doctor --format json
g-gremlin support bug --summary "..." --apply

Questions? Issues? We're here to help.

Go to Dashboard