# CLI

> CLI para desarrolladores de graph8 para rastrear fragmentos de código y formularios progresivos

Source: https://docs.graph8.com/es/developers/cli/

El CLI `g8` le da acceso por terminal a las herramientas de desarrollo de graph8: obtenga fragmentos de seguimiento específicos para cada framework y plantillas de formularios progresivos directamente desde su terminal.

> **Tip:**
> Pruebe el nivel de desarrollador de forma gratuita: 1,000 créditos, sin necesidad de tarjeta. [Comience](https://auth.graph8.com/en/signup).
>
> Agentes de IA: acceda al índice completo de documentación en [https://docs.graph8.com/llms.txt](https://docs.graph8.com/llms.txt).

> **Note:**
> ¿Busca el servidor MCP? El [Servidor MCP](https://docs.graph8.com/developers/mcp/) conecta agentes de IA mediante OAuth, sin necesidad de instalación. El CLI es una herramienta independiente para uso en terminal.

## Credenciales personales vs. de administrador

Para la mayoría de los usuarios, la autenticación del CLI debe provenir de su **Perfil**.

| Caso de uso | Dónde obtener las credenciales | Qué usar |
|----------|--------------------------|-------------|
| Uso personal del CLI en su equipo | **Perfil -> Desarrollador** | `g8 login` (OAuth) o clave API personal |
| Cuenta de servicio compartida o automatización a nivel de organización | **Configuración -> API** | Clave API de organización |

> **Tip:**
> Su token de acceso de PropelAuth del Perfil no es lo mismo que una clave API. Para los comandos del CLI, use `g8 login` o `G8_API_KEY`.

## Instalación

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

Esto instala el comando `g8`. Requiere Python 3.10+.

## Autenticación

Tres formas de autenticarse:

### `g8 login` (recomendado)

```bash
g8 login
```

Abre el navegador para iniciar sesión mediante OAuth. Una vez autenticado, el token se guarda en `~/.g8/credentials.json` y se utiliza automáticamente en todos los comandos posteriores. No se requiere clave API.

### Clave API

Si prefiere usar una clave API, utilice su **clave API personal** desde **Perfil -> Desarrollador**. Los administradores también pueden usar claves de organización desde **Configuración -> API** para integraciones compartidas.

**Guárdela localmente:**

```bash
g8 login --api-key
```

Le solicita que pegue una clave API, la valida y la guarda en `~/.g8/credentials.json`.

**O configúrela como variable de entorno:**

```bash
export G8_API_KEY="your_api_key_here"
```

> **Note:**
> **Precedencia:** variable de entorno `G8_API_KEY` > `~/.g8/credentials.json` (OAuth o clave API). La variable de entorno siempre tiene prioridad cuando ambas están presentes.

### `g8 logout`

Elimine las credenciales almacenadas:

```bash
g8 logout
```

### `g8 whoami`

Verifique el estado actual de su autenticación:

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

## Comandos

### `g8 snippet`

Obtenga el fragmento de seguimiento de graph8 para cualquier framework compatible. El fragmento carga `p.js`, el script de seguimiento de graph8, en cada página.

**Uso:**

```bash
# 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
```

**Opciones:**

| Opción | Descripción |
|--------|-------------|
| `--framework` | Framework de destino (requerido salvo que se use `--list`) |
| `--list` | Lista todos los frameworks compatibles |
| `--repo-id` | ID de repositorio para configuración específica (opcional) |
| `--format` | Formato de salida: `text` (predeterminado) o `json` |

**Frameworks compatibles:**

| Framework | Renderizado | Descripción |
|-----------|-----------|-------------|
| `html` | SSR | HTML / Vanilla JS: etiqueta script en `<head>` |
| `react` | CSR | React: componente `useEffect` |
| `nextjs` | SSR | Next.js: `next/script` para App Router y Pages Router |
| `vue` | CSR | Vue: composable `onMounted` |
| `wordpress` | SSR | WordPress: hook `functions.php` |
| `webflow` | SSR | Webflow: código personalizado en la configuración del proyecto |
| `shopify` | SSR | Shopify: fragmento `theme.liquid` |

> **Note:**
> Los frameworks **SSR** (renderizado en el servidor) cargan el fragmento en el layout HTML: está disponible desde el primer renderizado. Llame a `g8.track()` y `g8.identify()` directamente.
>
> Los frameworks **CSR** (renderizado en el cliente) inyectan el fragmento mediante `useEffect` u `onMounted` después de la hidratación. Use `window.g8?.track()` con encadenamiento opcional, ya que el script puede no estar listo de inmediato.

**Ejemplo de salida:**

```bash
$ 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"})
```

### Opciones de privacidad

El fragmento generado incluye atributos de datos que puede añadir para controlar el comportamiento de privacidad:

| Atributo | Valores | Descripción |
|-----------|--------|-------------|
| `data-privacy-dont-send` | `"true"` | Desactiva las cookies y el envío de eventos |
| `data-privacy-user-ids` | `"true"` | Desactiva el almacenamiento de identificadores de usuario |
| `data-privacy-ip-policy` | `"keep"`, `"stripLastOctet"`, `"remove"` | Controla el manejo de la dirección IP |
| `data-init-only` | `"true"` | Inicializa el script sin enviar un evento de página |

### Verificación del fragmento

Después de añadir el fragmento a su aplicación:

1. Abra **DevTools -> pestaña Red** en el navegador
2. Busque solicitudes a su host de seguimiento (`/p.js`)
3. En la **consola**: `window.g8` debe estar definido
4. Llame a `g8.track('test_event')`: debería ver una solicitud de red

---

### `g8 form`

Obtenga una plantilla de formulario progresivo: un formulario integrado o emergente que recopila datos por etapas a lo largo de múltiples visitas.

> **Caution:**
> El fragmento de seguimiento debe estar instalado antes de que los formularios funcionen. Ejecute primero `g8 snippet --framework <name>`.

**Uso:**

```bash
# 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
```

**Opciones:**

| Opción | Descripción |
|--------|-------------|
| `--framework` | Framework de destino (requerido) |
| `--variant` | Variante del formulario: `embedded` o `popup` (requerido) |
| `--repo-id` | ID de repositorio para configuración específica (opcional) |
| `--stages` | Etapas de campos personalizados como cadena JSON (opcional) |
| `--format` | Formato de salida: `text` (predeterminado) o `json` |

**Variantes de formulario:**

| Variante | Ideal para |
|---------|----------|
| `embedded` | Formularios integrados dentro del contenido de la página (secciones de registro, pies de página, barras laterales) |
| `popup` | Formularios modales o superpuestos activados por botones o eventos de página |

### Etapas del formulario progresivo

Los formularios recopilan datos de forma progresiva a lo largo de las visitas, solicitando un poco más cada vez. Las etapas predeterminadas son:

| Etapa | Campos | Propósito |
|-------|--------|---------|
| 1 | `work_email` | Captura inicial: mínima fricción |
| 2 | `first_name`, `last_name`, `company` | Enriquecimiento de identidad |
| 3 | `job_title`, `phone` | Datos de calificación |

El formulario registra qué etapa ha completado el visitante usando `localStorage` y muestra la siguiente etapa en su próxima visita.

**Etapas personalizadas:** pase un array JSON a `--stages` para reemplazar los valores predeterminados:

```bash
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"]}
    ]}
  ]'
```

### Flujo de datos

Cuando se envía un formulario, los datos fluyen a través del pipeline de seguimiento de graph8:

1. El formulario captura los valores de los campos del visitante
2. `g8.identify()` envía los datos al CDP de graph8
3. `g8.track()` registra el evento de envío del formulario
4. Los datos aparecen en el perfil del contacto en su espacio de trabajo de graph8

## Formatos de salida

| Formato | Indicador | Descripción |
|--------|------|-------------|
| Texto | `--format text` (predeterminado) | Salida legible con encabezados, bloques de código y pasos de configuración |
| JSON | `--format json` | Salida legible por máquina: misma estructura que la respuesta de la herramienta MCP |

El formato JSON es útil para redirigir a otras herramientas o scripts:

```bash
g8 snippet --framework html --format json | jq '.snippet_code'
```

## Flujo de trabajo

El orden recomendado para integrar graph8 en su aplicación:

1. **Instale el fragmento de seguimiento**: este es siempre el primer paso
```bash
   g8 snippet --framework nextjs
```

2. **Añada el fragmento a su aplicación**: siga los pasos de configuración indicados en la salida

3. **Configure el seguimiento**: añada llamadas de identificación y seguimiento:
```javascript
   // 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. **Añada formularios progresivos**: una vez que el seguimiento esté funcionando:
```bash
   g8 form --framework nextjs --variant embedded
```

5. **Verifique**: abra la pestaña Red de DevTools y busque solicitudes a su host de seguimiento

> **Tip:**
> ¿Prefiere `npm install @graph8/sdk` en lugar de la etiqueta script? Consulte la documentación del [SDK de JavaScript](https://docs.graph8.com/developers/sdk/).

---

## Comandos de CRM

### `g8 search-contacts`

Busque contactos que ya están en su CRM.

```bash
g8 search-contacts --job-title "VP Sales" --limit 10
g8 search-contacts --email john@acme.com
g8 search-contacts --company "Acme" --seniority VP
g8 search-contacts --list-id 637
```

| Opción | Descripción |
|--------|-------------|
| `--email` | Filtrar por correo electrónico (coincidencia exacta) |
| `--name` | Filtrar por nombre (coincidencia parcial) |
| `--job-title` | Filtrar por cargo (coincidencia parcial) |
| `--seniority` | Filtrar por antigüedad (C-Suite, VP, Director, Manager) |
| `--company` | Filtrar por nombre de empresa (coincidencia parcial) |
| `--country` | Filtrar por país |
| `--list-id` | Filtrar por ID de lista de contactos |
| `--page` | Número de página (predeterminado 1) |
| `--limit` | Resultados por página (predeterminado 25) |

### `g8 search-companies`

Busque empresas en su CRM.

```bash
g8 search-companies --industry "SaaS" --limit 10
g8 search-companies --domain acme.com
```

| Opción | Descripción |
|--------|-------------|
| `--domain` | Filtrar por dominio |
| `--industry` | Filtrar por sector |
| `--name` | Filtrar por nombre de empresa |
| `--page` | Número de página (predeterminado 1) |
| `--limit` | Resultados por página (predeterminado 25) |

### `g8 create-contact`

Cree un nuevo contacto en su CRM.

```bash
g8 create-contact --email jane@acme.com --first-name Jane --last-name Smith --job-title "VP Sales"
g8 create-contact --email john@startup.io --list-id 637
```

| Opción | Descripción |
|--------|-------------|
| `--email` | Correo electrónico profesional (requerido) |
| `--first-name` | Nombre |
| `--last-name` | Apellido |
| `--job-title` | Cargo |
| `--company-domain` | Dominio de la empresa |
| `--list-id` | Añadir a esta lista de inmediato |

### `g8 create-list`

Cree una nueva lista de contactos o empresas.

```bash
g8 create-list --title "VP Sales - SaaS SMB"
g8 create-list --title "Target Companies" --type companies
```

| Opción | Descripción |
|--------|-------------|
| `--title` | Nombre de la lista (requerido) |
| `--type` | `contacts` (predeterminado) o `companies` |

### `g8 add-to-list`

Añada contactos existentes a una lista.

```bash
g8 add-to-list --list-id 637 --contact-ids 5028106,5028105,5028104
```

| Opción | Descripción |
|--------|-------------|
| `--list-id` | ID de lista (requerido) |
| `--contact-ids` | IDs de contactos separados por comas (requerido) |

---

## Comandos de prospección

### `g8 lookup-person`

Busque una persona en el índice de datos de graph8, con más de 700M de registros. Cuesta 2 créditos por búsqueda, que solo se cobran cuando se encuentra una coincidencia.

```bash
g8 lookup-person --email mark.rubin@tiledb.com
g8 lookup-person --linkedin "linkedin.com/in/jane-smith"
g8 lookup-person --first-name Jane --last-name Smith --company-domain acme.com
```

| Opción | Descripción |
|--------|-------------|
| `--email` | Dirección de correo electrónico |
| `--linkedin` | URL de LinkedIn |
| `--first-name` | Nombre (úselo junto con apellido y dominio de empresa) |
| `--last-name` | Apellido |
| `--company-domain` | Dominio de la empresa |

### `g8 lookup-company`

Busque una empresa. Cuesta 2 créditos por búsqueda, que solo se cobran cuando se encuentra una coincidencia.

```bash
g8 lookup-company --domain tiledb.com
g8 lookup-company --name "Acme Corp"
```

### `g8 find-contacts`

Busque nuevos prospectos en el índice de datos abiertos. Se cobran créditos por resultado.

```bash
g8 find-contacts --filters '[{"field":"seniority_level","operator":"any_of","value":["VP","Director"]},{"field":"company_industry","operator":"contains","value":["SaaS"]}]' --limit 10
```

| Opción | Descripción |
|--------|-------------|
| `--filters` | Array JSON de objetos de filtro (requerido) |
| `--page` | Número de página (predeterminado 1) |
| `--limit` | Resultados por página (predeterminado 25) |

**Campos de filtro:** `first_name`, `last_name`, `work_email`, `job_title`, `seniority_level`, `company_name`, `company_domain`, `company_industry`, `company_employee_count`, `company_revenue`, `country`, `state`, `city`

**Operadores:** `any_of`, `contains`, `all_of`, `none_of`, `is_empty`, `is_not_empty`, `between`, `exists`

### `g8 find-companies`

Busque en la base de datos de empresas. Se cobran créditos por resultado.

```bash
g8 find-companies --filters '[{"field":"industry","operator":"contains","value":["SaaS"]},{"field":"employee_count","operator":"between","value":[50,500]}]'
```

### `g8 build-list`

Busque prospectos y guárdelos en una nueva lista. Se cobran créditos por contacto guardado.

```bash
g8 build-list --filters '[{"field":"seniority_level","operator":"any_of","value":["VP"]}]' --title "VP Sales - SaaS" --max-results 50
```

| Opción | Descripción |
|--------|-------------|
| `--filters` | Array JSON de filtros (requerido) |
| `--title` | Nombre de la lista (requerido) |
| `--max-results` | Máximo de contactos a guardar (predeterminado 100) |

> **Caution:**
> Esto crea contactos reales en su CRM y consume créditos. Previsualice primero con `find-contacts`.

---

## Enriquecimiento

### `g8 enrich`

Enriquezca contactos con correos electrónicos verificados, teléfonos y datos de empresa. Se cobran créditos por contacto.

```bash
g8 enrich --contact-ids 5028106,5028105,5028104 --list-id 637
```

| Opción | Descripción |
|--------|-------------|
| `--contact-ids` | IDs de contactos separados por comas (requerido) |
| `--list-id` | ID de la lista a la que pertenecen los contactos (requerido) |

---

## Secuencias

### `g8 sequences`

Liste las secuencias outbound disponibles.

```bash
g8 sequences --limit 10
```

### `g8 add-to-sequence`

Inscriba contactos en una secuencia outbound.

```bash
g8 add-to-sequence --sequence-id "0686895f-..." --contact-ids 5028106,5028105 --list-id 637
```

| Opción | Descripción |
|--------|-------------|
| `--sequence-id` | ID de secuencia obtenido con `g8 sequences` (requerido) |
| `--contact-ids` | IDs de contactos separados por comas (requerido) |
| `--list-id` | ID de lista (requerido) |

> **Caution:**
> Esto inscribe contactos en una prospección activa que envía correos electrónicos y mensajes reales. Verifique siempre antes de ejecutar.

### `g8 create-sequence`

Cree una nueva secuencia de prospección.

```bash
g8 create-sequence --name "Q2 VP Outbound" --description "Multi-step email + LinkedIn sequence"
```

| Opción | Descripción |
|--------|-------------|
| `--name` | Nombre de la secuencia (requerido) |
| `--description` | Descripción de la secuencia |
| `--steps` | Array JSON de configuraciones de pasos |
| `--channels` | Array JSON de configuraciones de canales |
| `--campaign-id` | Vincular a una campaña (opcional) |

### `g8 sequence-preview`

Previsualice los pasos y canales de una secuencia antes de iniciarla.

```bash
g8 sequence-preview --sequence-id "0686895f-..."
```

### `g8 update-sequence`

Actualice los metadatos de una secuencia.

```bash
g8 update-sequence --sequence-id "0686895f-..." --name "Updated Name" --description "New goal"
```

### `g8 pause-sequence`

Pause una secuencia activa. No se enviarán nuevos mensajes hasta que se reanude.

```bash
g8 pause-sequence --sequence-id "0686895f-..."
```

> **Caution:**
> Pausar detiene toda la prospección para los contactos en esta secuencia. Use `resume-sequence` para reiniciar.

### `g8 resume-sequence`

Reanude una secuencia pausada. Los tiempos de ejecución se recalculan respetando el horario laboral.

```bash
g8 resume-sequence --sequence-id "0686895f-..."
```

### `g8 sequence-analytics`

Obtenga métricas de rendimiento para una secuencia.

```bash
g8 sequence-analytics --sequence-id "0686895f-..."
```

Devuelve datos de resumen (total de contactos, tasa de finalización), rendimiento (embudo, tasas de respuesta), interacción (tasa de respuesta, tasa de rebote) y datos de línea de tiempo.

### `g8 delete-sequence`

Archive una secuencia (eliminación lógica). Las secuencias activas se pausan primero.

```bash
g8 delete-sequence --sequence-id "0686895f-..."
```

---

## Bandeja de entrada

### `g8 inbox-list`

Liste los hilos de respuesta en correo electrónico, SMS y LinkedIn.

```bash
g8 inbox-list --channel email --limit 20
g8 inbox-list --sequence-id "0686895f-..." --status unread
g8 inbox-list --assignee jane@company.com --tag qualified
```

| Opción | Descripción |
|--------|-------------|
| `--channel` | Filtrar por canal: `email`, `sms`, `linkedin` |
| `--sequence-id` | Filtrar por secuencia |
| `--status` | Filtrar por estado del hilo |
| `--assignee` | Filtrar por correo electrónico del usuario asignado |
| `--tag` | Filtrar por etiqueta |
| `--page` | Número de página (predeterminado 1) |
| `--limit` | Resultados por página (predeterminado 20) |

### `g8 inbox-get`

Obtenga un hilo de respuesta individual con el historial completo de mensajes.

```bash
g8 inbox-get --reply-id <thread-id> --channel email
```

### `g8 inbox-assign`

Asigne un hilo de respuesta a un miembro del equipo.

```bash
g8 inbox-assign --reply-id <thread-id> --assignee jane@company.com
```

### `g8 inbox-tag`

Etiquete un hilo de respuesta para su categorización.

```bash
g8 inbox-tag --reply-id <thread-id> --tag-ids "qualified,hot-lead"
```

### `g8 inbox-draft`

Genere un borrador de respuesta con IA basado en el contexto de la conversación. Consume créditos.

```bash
g8 inbox-draft --reply-id <thread-id>
```

### `g8 inbox-send`

Envíe una respuesta por correo electrónico, SMS o LinkedIn.

```bash
g8 inbox-send --reply-id <thread-id> --channel email --body "Thanks for your interest..."
```

> **Caution:**
> Esto envía un mensaje real al contacto. Verifique el contenido y el destinatario antes de ejecutar.

---

## Audiencias y sincronización con CRM

### `g8 sync-audience-list`

Liste las sincronizaciones de audiencias configuradas con plataformas publicitarias.

```bash
g8 sync-audience-list
```

### `g8 sync-audience-create`

Cree una nueva sincronización de audiencia con Meta, LinkedIn Ads, Google Ads o X.

```bash
g8 sync-audience-create --audience-id 42 --platform meta --mode mirror --cadence 24
```

| Opción | Descripción |
|--------|-------------|
| `--audience-id` | ID de audiencia o lista de origen (requerido) |
| `--platform` | Plataforma de destino: `meta`, `linkedin`, `google`, `x` (requerido) |
| `--mode` | Modo de sincronización: `mirror` (reemplazo completo) o `append_only` (requerido) |
| `--cadence` | Frecuencia de actualización en horas (0 = solo manual) |

### `g8 sync-audience-trigger`

Active manualmente una ejecución de sincronización.

```bash
g8 sync-audience-trigger --config-id <id>
```

### `g8 sync-audience-runs`

Vea el historial de ejecuciones de sincronización con recuentos de registros.

```bash
g8 sync-audience-runs --config-id <id>
```

### `g8 sync-audience-errors`

Vea los registros de errores de ejecuciones de sincronización fallidas.

```bash
g8 sync-audience-errors --config-id <id>
```

### `g8 sync-crm-list`

Liste las integraciones de CRM conectadas.

```bash
g8 sync-crm-list
```

### `g8 sync-crm-push`

Envíe contactos, empresas o membresías de listas a un CRM.

```bash
g8 sync-crm-push --provider hubspot --type contacts --records '[{"email":"jane@acme.com","properties":{"firstname":"Jane"}}]'
g8 sync-crm-push --provider salesforce --type companies --records '[{"Name":"Acme Corp","Website":"acme.com"}]'
```

| Opción | Descripción |
|--------|-------------|
| `--provider` | Proveedor de CRM: `hubspot`, `salesforce`, `pipedrive`, `zoho`, `sugarcrm` (requerido) |
| `--type` | Tipo de envío: `contacts`, `companies`, `lists` (requerido) |
| `--records` | Array JSON de registros a enviar (requerido) |

### `g8 sync-crm-fields`

Descubra los mapeos de campos disponibles para un proveedor de CRM.

```bash
g8 sync-crm-fields --provider hubspot
```

### `g8 sync-crm-status`

Verifique el estado de la conexión al CRM y los límites de frecuencia.

```bash
g8 sync-crm-status --provider salesforce
```

---

## Campañas

### `g8 campaigns`

Liste las campañas de su organización.

```bash
g8 campaigns --limit 10
```

### `g8 campaign`

Obtenga los detalles completos de una campaña específica.

```bash
g8 campaign 4781adce-464b-402e-9a69-b6dbb6376150
```

---

## Redirección y scripting

Todos los comandos generan salida en JSON, lo que los hace integrables en scripts:

```bash
# Extract emails from search results
g8 search-contacts --job-title "CTO" --limit 50 | jq '.[].work_email'

# Count contacts in a list
g8 search-contacts --list-id 637 | jq 'length'

# Export to CSV
g8 search-contacts --seniority VP --limit 100 | jq -r '.[] | [.first_name,.last_name,.work_email,.job_title] | @csv'
```