cotctl

CLI para la plataforma Cotalker

Features

• Gestión declarativa de recursos — crea, actualiza y exporta surveys via archivos YAML, similar a kubectl
• Autenticación OAuth con soporte multi-perfil para múltiples entornos
• Validación local de archivos YAML antes de aplicar cambios
• Export e import de recursos existentes como YAML o JSON
• Claude Code Skills — instala herramientas de IA para trabajar con Cotalker en tu editor
• MCP Server — conecta Claude Code con documentación técnica actualizada de Cotalker

Requisitos

• Node.js >= 18 (solo para la instalación via npm — el binario es standalone)

Instalación

npm install -g @cotctl/cli

Verificar instalación

cotctl --version

Quick Start

# 1. Autenticarse contra un entorno
cotctl login --url https://mycompany.cotalker.com

# 2. Ver perfil activo
cotctl profile list

# 3. Listar surveys disponibles
cotctl surveys list

# 4. Exportar una survey por code
cotctl surveys export <code> -o ./survey.yaml

# 5. Validar un archivo local
cotctl validate -f ./survey.yaml

# 6. Aplicar cambios al entorno
cotctl apply -f ./survey.yaml

Comandos

| Comando | Descripción | |---------|-------------| | cotctl login | Autenticarse y guardar un perfil de entorno | | cotctl logout [profile] | Cerrar sesión y eliminar un perfil | | cotctl profile | Listar, ver y gestionar perfiles guardados | | cotctl surveys list | Listar surveys del entorno | | cotctl surveys export <code> | Exportar surveys como YAML o JSON | | cotctl validate -f <file> | Validar un archivo YAML localmente | | cotctl apply -f <file> | Crear o actualizar un recurso desde YAML | | cotctl skills | Gestionar Claude Code Skills |

Para ayuda detallada de cualquier comando:

cotctl <command> --help

Autenticación

cotctl usa OAuth para autenticarse contra entornos Cotalker. El flow abre el navegador para completar el login:

cotctl login --url https://mycompany.cotalker.com

Para entornos sin navegador (CI/CD), usa --no-browser:

cotctl login --url https://mycompany.cotalker.com --no-browser

Multi-perfil

cotctl soporta múltiples perfiles para trabajar con distintos entornos:

# Usar un perfil específico en cualquier comando
cotctl surveys list --company staging

# Ver todos los perfiles guardados
cotctl profile list

Los perfiles se guardan en ~/.cotctl/config.json.

Claude Code Skills

cotctl incluye Skills para Claude Code que instalan herramientas y conocimiento especializado de Cotalker directamente en tu editor.

Skills disponibles

| Skill | Descripción | |-------|-------------| | cotctl-surveys | Crear y modificar YAMLs de surveys vía cotctl | | cotctl-apply | Aplicar recursos YAML a entornos Cotalker | | cotctl-export | Exportar y consultar recursos desde Cotalker | | cotctl-roles | Crear y gestionar roles de acceso y permisos en Cotalker | | cotctl-properties | Generar tipos de propiedades y propiedades para Cotalker | | cotctl-workflows | Crear y gestionar workflows, máquinas de estado y tareas | | cotalker-docs | Conocimiento general de la plataforma Cotalker |

Gestión de skills

# Listar skills disponibles
cotctl skills list

# Instalar (selector interactivo)
cotctl skills install

# Instalar uno específico globalmente
cotctl skills install cotctl-surveys --global

# Desinstalar
cotctl skills uninstall cotctl-surveys --global

MCP Server

cotctl puede configurar la conexión con el servidor MCP de Cotalker RAG, que permite a Claude Code acceder a documentación técnica actualizada de la plataforma.

La conexión MCP se configura automáticamente al instalar un skill (a menos que uses --no-mcp).

Agrega a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cotalker-rag": {
      "type": "http",
      "url": "https://llm.cotalker.com/mcp"
    }
  }
}

Agrega a .mcp.json en la raíz de tu proyecto (scope local) o ~/.claude/settings.json (scope global):

{
  "mcpServers": {
    "cotalker-rag": {
      "type": "http",
      "url": "https://llm.cotalker.com/mcp"
    }
  }
}

O usa cotctl directamente:

# Scope global
cotctl mcp install --scope global

# Scope local (proyecto actual)
cotctl mcp install --scope local

Documentación

Para documentación detallada de cada comando:

cotctl <command> --help

Para instalar skills con documentación integrada para Claude Code:

cotctl skills install