oko-cli 0.3.0

Elegant CLI for API endpoint testing

OKO CLI

OKO es una CLI ligera para probar APIs y endpoints desde terminal.

Diseñada para flujo rápido: colecciones, aliases claros, variables, ejecución inmediata y salida legible.

---

¿Qué resuelve?

• Organizar endpoints por colección
• Reutilizar variables globales ({{base_url}}, {{token}}, etc.)
• Ejecutar requests con params, headers y body JSON
• Pedir variables faltantes de forma interactiva
• Reutilizar valores anteriores con defaults por historial
• Previsualizar requests sin enviarlas (--dry-run)

---

Instalación

pip install oko-cli

Inicio rápido

oko init

---

Ejemplo completo (API ficticia)

Para documentar comandos de forma consistente, usaremos una API ficticia:

• Nombre: Aurora Store API
• Base URL: https://api.aurora-store.test
• Recurso principal: products

1) Crear colección

oko collection add catalog
oko collection list

2) Configurar variables globales

oko variable add base_url=https://api.aurora-store.test
oko variable add auth_token=demo-token-123
oko variable list

3) Registrar endpoints con aliases claros

# Listar productos
oko endpoint add catalog ProductsList '{{base_url}}/products' --method GET

# Buscar por categoría con paginación
oko endpoint add catalog ProductsByCategory '{{base_url}}/products?category={{category}}&take={{take}}&skip={{skip}}' --method GET

# Obtener detalle por id
oko endpoint add catalog ProductDetail '{{base_url}}/products/{{product_id}}' --method GET

# Crear producto
oko endpoint add catalog ProductCreate '{{base_url}}/products' --method POST

oko endpoint list catalog

4) Ejecutar endpoints

Ejecución directa:

oko endpoint run catalog ProductsList

Con variables runtime (forma larga):

oko endpoint run catalog ProductsByCategory \
  --var category=hoodies \
  --var take=10 \
  --var skip=0

Con variables runtime (forma compacta):

oko endpoint run catalog ProductsByCategory --vars category=hoodies,take=10,skip=0

Con headers:

oko endpoint run catalog ProductDetail \
  --var product_id=42 \
  -H Authorization='Bearer {{auth_token}}'

Con body JSON:

oko endpoint run catalog ProductCreate \
  --json '{"name":"Aurora Hoodie","price":49.9,"inventory":25}'

5) Prompt interactivo de variables faltantes

Si ejecutas un endpoint sin pasar todas las variables necesarias, OKO las solicita:

oko endpoint run catalog ProductsByCategory

Notas:

• Si ya usaste valores antes, aparecerán como default en el prompt.
• Presiona Enter para reutilizar el valor sugerido.

6) Validar sin enviar request (--dry-run)

oko endpoint run catalog ProductsByCategory --vars category=hoodies,take=5,skip=0 --dry-run

Muestra request final resuelta (método, URL, params, headers, JSON) sin hacer llamada HTTP.

7) Ejecución no interactiva

Útil para CI/scripts cuando quieres fallar si faltan variables:

oko endpoint run catalog ProductsByCategory --no-prompt-missing

---

Sintaxis de variables

OKO resuelve variables en:

• URL
• Query params
• Headers
• JSON body

Ejemplos:

{{base_url}}
{{auth_token}}
{{user.id}}

---

Comandos de referencia rápida

oko init
oko collection add <name>
oko collection list
oko variable add <key>=<value>
oko variable list
oko variable delete <key>
oko endpoint add <collection> <alias> <url> --method <GET|POST|PUT|PATCH|DELETE>
oko endpoint list <collection>
oko endpoint run <collection> <alias> [opciones]

Opciones útiles de endpoint run:

• --var key=value (repetible)
• --vars key1=v1,key2=v2
• -p key=value (query param)
• -H key=value (header)
• --json '{...}'
• --prompt-missing / --no-prompt-missing
• --dry-run

---

Filosofía

OKO es intencionalmente simple:

• Sin UI
• Sin cuentas
• Sin sincronización
• Sin dependencia de nube

Solo terminal, endpoints y foco.

---

Requisitos

• Python 3.8+

Estado

Proyecto en desarrollo activo.