Your First Gremlin Run

Let your AI agent accelerate setup.

Fast Path (AI-Assisted)

After you request beta access, we will email you a setup prompt. Paste it into Claude Code or another coding agent. If browser auth or live API checks are blocked there, run those specific commands in your local terminal and paste results back.

Example prompt (your token will be included automatically):

Please help me set up FoundryOps Agent (g-gremlin).

1. Check Python is 3.11+.
2. Install with pipx:
   - python -m pip install --user pipx
   - python -m pipx ensurepath
   - python -m pipx install --force g-gremlin
3. Authenticate: g-gremlin auth login --token [YOUR_TOKEN_HERE]
4. Verify local status: g-gremlin auth status
5. Verify doctor: g-gremlin doctor
6. If using HubSpot:
   - Prefer OAuth: g-gremlin hubspot oauth connect --workspace-id <WORKSPACE_ID>
   - Fallback (advanced): g-gremlin hubspot connect --access-token <pat-na1-...>
   - g-gremlin hubspot whoami
   - g-gremlin hubspot doctor --json

If HubSpot fails with DNS/network errors in this environment, tell me to run
the same commands in my local terminal plus:
nslookup api.hubapi.com

Show each command output and stop on errors.

✓

Use AI for orchestration, local terminal for blocked steps

Your AI agent can guide install/auth/config. Browser OAuth and live API checks may need your local terminal.

Advanced: Manual installation reference (click to expand)

Install g-gremlin

Install the CLI with pipx. Requires Python 3.11+.

python -m pip install --user pipx
python -m pipx ensurepath
python -m pipx install --force g-gremlin
python -m pipx list

Restart your terminal, then verify with g-gremlin --version. If "command not found", run python -m pipx ensurepath and restart the terminal.

Authenticate

Get your token from the beta access confirmation email.

g-gremlin auth login --token <your-token>

Then run g-gremlin auth status. The CLI caches your license locally and refreshes automatically.

Connect integrations

Connect the systems you selected. 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

g-gremlin pull SHEET_ID --range A1:A1

The first Google command opens a browser for OAuth login.

HubSpot

# Recommended OAuth flow
g-gremlin hubspot oauth connect --workspace-id <WORKSPACE_ID>

# Advanced fallback (PAT)
g-gremlin hubspot connect --access-token <pat-na1-...>

Do not use g-gremlin auth set hubspot for this flow.

Verify

Run status and doctor commands to confirm everything is connected.

g-gremlin auth status
g-gremlin doctor

For HubSpot, run g-gremlin hubspot whoami and g-gremlin hubspot doctor --json. If DNS/network fails in an AI environment, retry in local terminal with nslookup api.hubapi.com.

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"

# 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 fails in an AI environment, treat DNS/network checks as environment-limited and retry from local terminal first.
For Salesforce updates, always use sfdc preview-push first to review changes.

What's Next?

Full Command Reference

Every Gremlin command with examples.

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

Back to Home