Cada clic en la interfaz de Sharkly es una decisión que toma una persona: crear esta tarea, asignar aquel agente, revisar una ejecución. Esa es la interfaz adecuada para las decisiones que requieren criterio. Y es la interfaz equivocada para la milésima repetición de la misma decisión. Cuando tu equipo decide que toda compilación nocturna fallida debe convertirse en una tarea, que una persona vaya clicando por pantallas deja de ser un flujo de trabajo y pasa a ser una obligación tediosa.
Aquí es donde entra la superficie programática. La CLI de Sharkly permite que personas, agentes y scripts trabajen con Sharkly desde una terminal: gestionar los recursos de la organización, registrar una computadora para la ejecución de agentes, inspeccionar el servicio local y automatizar flujos de trabajo repetibles. Detrás de ella hay una API REST en api.sharkly.ai que acepta los mismos tokens de acceso personal que usa la CLI.
Esto importa más en Sharkly que en una herramienta de gestión de proyectos típica, porque Sharkly no es solo el lugar donde se describe el trabajo. Es donde se ejecuta el trabajo. Sharkly añade la capa compartida de tareas, computadoras, contexto, control y revisión en torno a herramientas de programación como Claude Code y Codex, de modo que un sharkly task create scriptado no se limita a abrir un ticket. Si la tarea está asignada a un agente y se encuentra en un estado listo, puede iniciar una ejecución real en una computadora real. Automatizar la superficie significa automatizar la fuerza de trabajo.
TL;DR
La CLI de Sharkly (comando sharkly) permite que personas, agentes y scripts trabajen con Sharkly desde una terminal, y también es la vía por la que se instala el servicio local en hosts remotos y Linux para que puedan unirse a tu flota como computadoras. La autenticación está deliberadamente dividida: un token de acceso personal (prefijo shk_) inicia sesión en nombre de una persona o un script, un token de instalación de un solo uso (prefijo sit_) registra una computadora, y las ejecuciones de agentes usan una credencial de ejecución con alcance limitado que proporciona Sharkly. Con un token en su sitio, los scripts pueden crear y editar tareas, comentarlas, inspeccionar ejecuciones y registros, y gestionar computadoras, todo con --output json para un análisis limpio. El mismo token shk_ funciona como token de portador contra la API REST, y los disparadores de webhook de Automations permiten que CI y otros sistemas externos inicien ejecuciones de agentes con una solicitud POST.
Una plataforma, dos superficies
La interfaz de Sharkly y su superficie programática son dos entradas al mismo sistema. La tarea que crea tu script es la misma tarea que ve un compañero en el tablero, con el mismo estado, flujo de trabajo, comentarios e historial de ejecución. Automatizar nunca rodea el registro compartido: la automatización alimenta el sistema de registro.
Una forma útil de dividir ambas es por quién decide. Usa la interfaz cuando una persona esté tomando una decisión con criterio: dar forma a un requisito, revisar un diff, aceptar un resultado. Usa la CLI o la API cuando la decisión ya esté tomada y solo se repita la mecánica: registrar tareas desde un sistema de monitorización, volcar los registros de ejecución en un panel, comprobar el estado de una computadora desde un cron. Un script puede crear la tarea e incluso lanzar la ejecución, pero la aceptación sigue en manos de una persona.
Instalar la CLI y qué instala
En macOS o Linux, el instalador oficial es un solo comando:
curl -fsSL https://file-assets.sharkly.ai/download/install.sh | bash
Windows tiene un instalador oficial de PowerShell, actualmente solo para AMD64. En cualquier plataforma, verifica y mantén la instalación con:
sharkly version
sharkly update
La CLI cumple un segundo papel además de ser un cliente. La documentación describe dos vías para conectar una computadora: instalar Sharkly Desktop en un ordenador personal compatible, o instalar la CLI de Sharkly y el servicio local en un host remoto o una computadora Linux. Esa segunda vía es la forma en que un servidor de compilación, un equipo Linux de reserva o un contenedor se convierten en capacidad de ejecución para tus agentes. El servicio local que configura registra la computadora, detecta los runtimes instalados, envía latidos, recibe las ejecuciones en cola, prepara los directorios de tareas y transmite el progreso de vuelta, iniciando él mismo la conexión para que no se requiera ningún puerto de entrada.
Si todavía estás conectando tu primera máquina desde la interfaz, la guía de introducción cubre ese proceso.
Tres credenciales, tres funciones
Sharkly usa credenciales distintas para propósitos distintos, y merece la pena interiorizar esa separación antes de automatizar nada.
Un token de acceso personal empieza por shk_ y permite que la CLI, un script u otro cliente de confianza actúen como tu cuenta de usuario. Se crea en Settings, eliges una caducidad de 30 días, 90 días, 1 año o sin caducidad, y copias el valor completo una sola vez al crearlo. Inicia sesión con el flujo basado en indicaciones para que el token nunca acabe en el historial del shell:
sharkly login --token
sharkly auth status
Un token de instalación de computadora empieza por sit_, caduca a los 30 minutos y puede usarse exactamente una vez. Su única función es registrar una computadora:
sharkly computer register --install-token sit_...
La tercera credencial nunca la manejas tú: una ejecución de agente activa recibe una credencial de ejecución con alcance limitado que proporciona Sharkly, restringida a las familias de comandos que permite su contexto de ejecución.
La documentación traza la frontera con claridad: un token de acceso personal no registra una computadora, y un token de instalación no crea un inicio de sesión humano en la CLI. El registro crea una sesión independiente del servicio local, y por eso revocar tu token personal más adelante no deja desconectadas tus computadoras registradas. Del mismo modo, sharkly auth logout solo borra el token de tu perfil local; el token sigue siendo válido en el servidor hasta que lo revoques en Settings.
Para CI, sáltate por completo el flujo de inicio de sesión. La CLI lee el token de la variable de entorno SHARKLY_TOKEN, que tiene prioridad sobre cualquier perfil guardado. Rellénala desde un almacén de secretos protegido, como los secretos de GitHub Actions, en lugar de escribirla en el archivo del flujo de trabajo, y mantén la organización explícita con --organization-id.
Gestionar una flota de computadoras desde la terminal
Una vez registrados los hosts, el grupo de comandos sharkly computer cubre la inspección y el mantenimiento sin necesidad de un navegador:
sharkly computer list --output json
sharkly computer show <computer-id> --output json
sharkly computer usage <computer-id> <runtime-id> --days 30 --output json
sharkly computer ping <computer-id> <runtime-id> --wait --output json
sharkly computer update <computer-id> <runtime-id>
list muestra las computadoras registradas en la organización actual, show devuelve una computadora con sus runtimes, usage inspecciona un runtime concreto, ping comprueba si ese runtime puede completar un recorrido de ida y vuelta, y update solicita una actualización de la CLI para un runtime. La distinción por la que existe ping: que una computadora esté en línea solo significa que su servicio local está enviando latidos, no que un runtime determinado pueda ejecutar una ejecución ahora mismo.
En el propio host, el diagnóstico rutinario usa los comandos orientados al usuario:
sharkly computer status --output json
sharkly computer logs --lines 100
El espacio de nombres daemon expone el ciclo de vida del proceso y los controles de disco, incluidos sharkly daemon disk-usage y sharkly daemon cleanup, que es una simulación a menos que añadas --confirm. La regla de decisión de la documentación: prefiere computer status y computer logs para el diagnóstico rutinario, y recurre a daemon solo cuando necesites el ciclo de vida del proceso, informes de disco o limpieza. La entrada sobre las computadoras de esta serie profundiza en la propiedad, la visibilidad y las políticas de limpieza.
Automatizar tareas: trabajo que llega sin reunión
Las tareas son donde la CLI se gana su lugar en una canalización. La familia de comandos se lee como una versión scriptable del tablero:
sharkly task list --output json
sharkly task search "authentication error" --output json
sharkly task create --title "Investigate authentication error" --output json
sharkly task edit <task-id> --status <status> --output json
sharkly task comment <task-id> --body "Investigation started." --output json
El caso de uso obvio en CI es registrar trabajo automáticamente. Un trabajo nocturno que detecta un lanzamiento fallido no necesita a nadie rellenando un formulario:
sharkly task create \
--title "Investigate the failed release" \
--body-file ./task-body.md \
--output json
Usa --body-file o --body-stdin siempre que el contenido exacto importe, ya que la forma corta --body decodifica secuencias de escape. Y como una tarea asignada a un agente inicia una ejecución cuando se encuentra en un estado listo, ese único comando puede ser el inicio de un bucle totalmente automatizado: el script registra la tarea, el agente asignado la toma, y la ejecución, los bloqueos y el resultado vuelven a la tarea, donde una persona los revisa a la mañana siguiente.
Los scripts de informes obtienen filtros de verdad en lugar de cribado en el lado del cliente. Puedes filtrar por antigüedad del estado con --status-changed-within 7d, y por campos personalizados:
sharkly task list --space HF --field "Customer Tier=VIP" --output json
Los indicadores --field repetidos se combinan con AND, la coincidencia tiene en cuenta el tipo y es exacta, y el filtrado ocurre en el servidor antes de la paginación. Adopta sin reservas las convenciones de scripting de la documentación: solicita --output json explícitamente, añade --color never y --quiet, mantén --organization-id visible y usa set -euo pipefail. Los códigos de salida son contractuales: 0 para éxito, 1 para errores de comando, validación, autenticación o API remota, y 2 para condiciones transitorias del servicio local o de la red, lo que hace que la lógica de reintentos sea sencilla.
La CLI también se describe a sí misma. sharkly schema task create --format json expone el registro de comandos en formato legible por máquina, y sharkly tldr task muestra escenarios seleccionados, algo que importa cuando lo que escribe el script es, a su vez, un agente.
Observar ejecuciones sin abrir un panel
La ejecución es observable a través de la misma superficie:
sharkly run list --task <task-id> --output json
sharkly run view <run-id> --output json
sharkly run log <run-id> --since <sequence> --output json
sharkly run cancel <run-id> --output json
El indicador --since hace que el sondeo sea sensato: un script de monitorización registra el último número de secuencia procesado y recupera solo los mensajes más recientes en cada pasada. Combínalo con sharkly agent list, sharkly automation view y sharkly automation runs, y podrás construir una página de estado para tu fuerza de trabajo de agentes con un script de shell y jq.
La API REST y los webhooks
Todo lo que hace la CLI se apoya en la API REST, y la documentación muestra la vía directa: envía tu token de acceso personal como token de portador por HTTPS.
curl -fsS https://api.sharkly.ai/rest/v1/users/current \
-H "Authorization: Bearer ${SHARKLY_TOKEN}"
El acceso a través de la API está limitado por los permisos del usuario que hay detrás del token; el modelo de tokens actual no permite seleccionar el alcance por token, lo que es una buena razón para crear un token independiente para cada servicio con una caducidad definida. La referencia de endpoints está en docs.sharkly.ai, y las respuestas --output json de la CLI son una vista fiel de las estructuras con las que trabajarás.
El tráfico también fluye en sentido contrario. Una Automation puede llevar un disparador de webhook: Sharkly genera una URL secreta que acepta una solicitud POST, y una solicitud válida inicia la ejecución del agente o del equipo de la Automation. La URL completa se muestra una sola vez y actúa como secreto de portador de forma predeterminada, con verificación de firma opcional. Esta es la mitad entrante de la historia de CI: tu canalización diciéndole a Sharkly «ha pasado algo, ejecuta el agente de triaje».
Merece la pena ser preciso sobre lo que esta superficie no es. La CLI de Sharkly no es otro agente de programación, y la API no es un endpoint de modelo. Los runtimes como Claude Code y Codex realizan la ejecución; la superficie programática de Sharkly gestiona la capa que los rodea. Esa neutralidad la separa de opciones atadas a un ecosistema como GitHub Agent HQ, donde la superficie de automatización y la ejecución viven dentro de los muros de un único proveedor.
Por dónde empezar
Empieza más pequeño de lo que crees. Crea un token de acceso personal con una caducidad de 90 días, ejecuta sharkly login --token y automatiza la lectura más aburrida que haces cada día, como una lista de tareas canalizada por jq hacia un resumen matutino. Las lecturas son seguras y te enseñan las estructuras JSON. Luego automatiza una escritura con un disparador evidente, como crear una tarea a partir de un trabajo de CI fallido. Conecta un disparador de webhook solo después de que ambos te resulten rutinarios.
El patrón que hay que preservar es aquel sobre el que está construida toda la plataforma: los scripts y los agentes generan y ejecutan el trabajo, y el contexto, el progreso, los bloqueos, los resultados y la revisión humana permanecen visibles desde la solicitud hasta la entrega. Automatiza las entradas. Conserva la revisión.
Preguntas frecuentes
¿Necesito la CLI para usar Sharkly?
No. Sharkly Desktop cubre la conexión de un ordenador personal, y la aplicación web cubre el trabajo diario con tareas. La CLI se vuelve necesaria cuando conectas un host remoto o una computadora Linux, ya que instalar la CLI de Sharkly y el servicio local es la vía de configuración documentada en esos casos, y resulta valiosa siempre que un flujo de trabajo se repita lo suficiente como para que ir clicando por él suponga un coste.
¿Cuál es la diferencia entre un token de acceso personal y un token de instalación?
Un token de acceso personal (prefijo shk_) autentica a una persona o a un script como tu cuenta de usuario, para inicios de sesión en la CLI, trabajos de CI y solicitudes directas a la API. Un token de instalación de computadora (prefijo sit_) es de un solo uso y de corta duración, caduca a los 30 minutos, y solo registra una computadora. Ninguno sustituye al otro.
¿Puedo llamar directamente a la API REST de Sharkly en lugar de usar la CLI?
Sí. Envía un token de acceso personal como token de portador por HTTPS a api.sharkly.ai; la documentación muestra curl -fsS https://api.sharkly.ai/rest/v1/users/current con una cabecera Authorization: Bearer como patrón. El token lleva los permisos de tu cuenta de usuario.
¿Cómo creo una tarea desde una canalización de CI?
Guarda un token shk_ como secreto protegido de CI y expórtalo como la variable de entorno SHARKLY_TOKEN, que la CLI lee automáticamente. Después ejecuta sharkly task create con --title, --body-file para contenido multilínea exacto, un --organization-id explícito y --output json para que el trabajo pueda capturar el ID de la tarea creada.
¿Revocar mi token de acceso personal detiene mis computadoras registradas?
No. El registro de una computadora crea una sesión independiente del servicio local mediante el token de instalación, así que revocar un token de acceso personal no detiene esas computadoras. La revocación sí invalida el token en todos los lugares donde se use para solicitudes de CLI, API y automatización, por lo que la rotación debería actualizar los scripts dependientes antes de revocar el token antiguo.
