dadasmuk/slipdock

CLI de Slipdock

El comando slipdock se comunica con la aplicación Slipdock del usuario — alojada en app.slipdock.us, o en servidores autogestionados accesibles desde su dirección. Cada escritura aparece en vivo en la interfaz web. Ejecuta slipdock --help para la referencia completa.

Servidor indicado. La variable $SLIPDOCK_URL, o el archivo ~/.config/slipdock/url (escrito por slipdock url <dirección>, o por el propio script /install.sh del servidor), o la dirección tailnet de esta máquina en el puerto :4000. Si ninguna de estas corresponde al tablero que el usuario quiere, pregúntale la dirección — no adivines.

Si vas a trabajar desde el tablero — tomar la siguiente tarea, trabajar en una épica, mantener las tarjetas actualizadas mientras trabajas — ejecuta primero slipdock guide (las propias instrucciones del servidor para agentes: épicas y subtarjetas, cómo elegir la siguiente tarjeta, qué escribir de vuelta) y síguelas. Este archivo es la referencia de comandos; la guía es el flujo de trabajo.

Si las herramientas MCP de Slipdock están conectadas

Cuando esta sesión ya tiene herramientas de Slipdock (list_boards, get_card, create_card, complete_card…, desde /mcp del servidor), son una alternativa a la CLI para el mismo trabajo: usa la que esté presente. Las convenciones son las mismas en ambos casos — get_guide devuelve la versión breve de la guía que imprime slipdock guide, terminando con los nombres de sus otras secciones; section: "automations" (o cualquiera de esos nombres, o "all") da una de ellas. archive_card guarda una tarjeta, y restore: true la recupera; archive_board hace lo mismo para un tablero. Prefiere esas: delete_card (necesita confirm: true), delete_list y delete_board (confirm es el código del tablero) no se pueden deshacer. create_list, create_tag y create_board añaden estructura (una etiqueta debe existir antes de que create_card/update_card pueda ponerla en una tarjeta). list_cards con full: true lee todas las tarjetas por completo (comentarios, lista de verificación, documentos) en una sola llamada en lugar de un get_card cada una. update_card también establece dependencias y trabaja con la lista de verificación. list_pages lista la wiki de un tablero (tree: true la anida, como lo hace page tree), y read_page lee una. page_info responde lo que hacen page links, page sections, page wanted y page resolve — pregúntale por sections antes de una edición de sección con write_page en lugar de adivinar la ruta del encabezado. page_history es page history y page diff (rev, rev + against para comparar dos versiones, o diff: true para la última guardada), y revert_page es page revert: necesita el content_hash actual de la página como base_hash. update_page es page edit --title/--summary/--tag, page mv, page file, page rm/page restore (archived) y page pin --card (pin_card/unpin_card). upload_file es attach para un archivo de hasta 10 MB (content_base64, o text). La base64 que un modelo escribe se daña por encima de ~1 KB (#1040), así que cuando haya un shell con el archivo, no lo envíes: usa slipdock attach, o upload_file con card/page y link: true (#1147), que responde con un upload_url de un solo uso, válido por 10 minutos y sin token, para curl -F file=@FILE -F sha256=<hex> <upload_url> (también filename, replace, hide_on_card), manteniendo los bytes fuera del modelo. download_file con link: true funciona igual al revés: curl -fsSo FILE <download_url>. Un archivo ya en la wiki sincronizada del usuario es copiado por el servidor con wiki_file (su ruta en tu wiki, o su id; sin contenido). content_base64 debe llevar sha256 (hexadecimal, de los bytes antes de base64), y un rechazo por sha256_mismatch significa recodificar y reenviar. El sha256 en la respuesta es de los bytes tal como se almacenaron, y get_card/read_page lo listan para cada archivo: compáralo con el hash de la fuente para verificar un archivo, en lugar de descargarlo. Cualquier cosa de más de unos pocos KB se envía en fragmentos de ~4 KB (#1016), ya que cuanto más larga es la base64, más probable es que se dañe: el primero con append: true, card/page, filename y el sha256 de ese fragmento devuelve un upload_id; cada siguiente envía upload_id, append: true, offset (el received de la última respuesta) y su propio sha256, y un fragmento rechazado se reenvía por sí solo; luego upload_id, finish: true y el sha256 del archivo completo crea el adjunto. No aparece nada en la tarjeta antes de eso. Una reconstrucción de un archivo ya existente en la tarjeta envía replace: true (en la llamada única, el primer fragmento o finish): los archivos anteriores con ese nombre desaparecen una vez que se almacena el nuevo, dejando solo una copia actual. delete_attachment (detach; el id del attachment y confirm: true) elimina uno directamente, como un archivo que subiste por error. Y download_file lee un archivo adjunto por su id (get_card y read_page los listan). list_automations es automations/automation (vocabulary: true añade lo que dan automation-help y automation-presets), y manage_automation es new-automation (action: create), set-automation (update) y delete-automation (delete, con confirm: true). list_tools es tools/tools show (el tipo de cada herramienta y installed.board, el tablero que creó tu instalación; con file, tools file; skill lee su SKILL.md; link: true da un download_url de un solo uso para el archivo, el zip de la habilidad o el tarball de habilidades, #1158; package: true, tools download), e install_tool es tools install-board. Todo lo que no cubren las herramientas (ejecutar una regla ahora, callbacks y alertas, sprints, archivos de más de 10 MB, campos) sigue siendo la CLI o la API.

Si la CLI no está instalada aquí

Todo lo que sigue es un envoltorio sobre una API JSON, y la API es la alternativa: solo necesita curl. No le digas al usuario que instale la CLI (es un escript y necesita Erlang) — usa la API, y menciona la CLI solo si pide algo más cómodo de escribir, o para la sincronización de la wiki, que solo la CLI hace. En Windows es una línea en PowerShell, desde su propio servidor: irm "$B/cli/install.ps1" | iex, luego slipdock auth. En otros lugares se compila desde el repositorio cli/.

B="${SLIPDOCK_URL:-$(cat ~/.config/slipdock/url 2>/dev/null)}"
T="$(cat ~/.config/slipdock/token 2>/dev/null)"
H="Authorization: Bearer ${SLIPDOCK_TOKEN:-$T}"

curl -s "$B/api/guide"                 # no necesita token; toda la API, con curl para cada llamada
curl -s -H "$H" "$B/api/me"            # quién es el token

GET /api/guide es la referencia completa — cada endpoint, con una línea curl para él, además de los tableros y listas del propio usuario cuando se pasa un token. Léelo en lugar de inferir rutas desde este archivo.

Iniciar sesión tampoco necesita la CLI; es el mismo flujo de dispositivo, dos llamadas (la guía las detalla). Pide un código, muestra al usuario la URL y el código, sondea hasta que apruebe, luego escribe el token en ~/.config/slipdock/token con modo 600 para que la siguiente sesión lo tenga:

curl -s -X POST "$B/api/auth/device" -H 'content-type: application/json' \
     -d '{"label":"claude en esta máquina","scope":"write"}'
# → user_code, verification_uri, device_code, interval
curl -s -X POST "$B/api/auth/device/token" -H 'content-type: application/json' \
     -d '{"device_code":"…"}'
# → 400 authorization_pending hasta que se apruebe, luego {"token":"…"}

Para instalar estas habilidades en una máquina que no tiene ninguna: curl -fsSL "$B/install.sh" | sh (solo necesita curl y tar); en Windows, en PowerShell, irm "$B/install.ps1" | iex (en %USERPROFILE%\.claude\skills, no en el home de WSL). Para ChatGPT, que no puede ejecutar esta CLI, slipdock skills chatgpt las guarda como zips para subir, mapeando cada comando a las herramientas del conector MCP ($B/api/skills/<nombre>/chatgpt.zip).

Iniciar sesión

La API necesita un token. Si un comando falla con no has iniciado sesión, ejecuta slipdock auth — imprime un código corto y una URL, el usuario lo aprueba en un navegador donde ya haya iniciado sesión, y tienes un token unos segundos después. Diles el código y la URL; no les pidas que vayan a crear un token manualmente a menos que prefieran hacerlo (slipdock auth <token> todavía acepta uno, y SLIPDOCK_TOKEN sigue funcionando).

slipdock whoami muestra el usuario actual. Los tableros a los que el usuario no puede acceder simplemente no se muestran; un error forbidden significa que pueden ver algo pero no cambiarlo. Dos rechazos mencionan el token en lugar del usuario, y significan que el token que tienes está deliberadamente limitado en lugar de que algo esté roto — dilo así en lugar de reintentar:

• this API token is read-only — se concedió solo acceso de lectura. Pide uno de lectura/escritura.
• this API token's scope doesn't allow it — está restringido a tableros particulares, o no es un token de administrador y has intentado administrar el servidor.

Dos rechazos más también son definitivos. Repórtalos y di lo que la persona puede hacer:

• card_limit_reached (HTTP 402) — la cuenta del propietario del tablero ha agotado todos los elementos que permite. Un elemento es una tarjeta, una página wiki o un archivo subido; los tres cuentan contra un mismo número, así que escribirlo como página no lo solucionará. Un título diferente tampoco ayudará; fallará de la misma manera, para siempre. Sugiere archivar algo terminado. slipdock whoami --json y slipdock guide indican cuánto del límite queda, para que puedas verificar antes de empezar un lote en lugar de descubrir el límite a medio camino.
• board_limit_reached (HTTP 402) — poseen tantos tableros como este servidor permite a una persona. Los subtableros (subcards) no cuentan para el límite. Sugiere archivar un tablero o pedirle a un administrador.
• storage_limit_reached (HTTP 402) — sus archivos subidos llenan el espacio permitido. Solo eliminar adjuntos lo libera; archivar la tarjeta de la que cuelga el archivo no lo hace.
• trial_expired (HTTP 402) — una prueba gratuita ha caducado. No se puede añadir nada nuevo en ninguno de sus tableros, por pequeño que sea. Todo lo que ya está allí sigue siendo legible y editable. No hay nada que puedas hacer al respecto: dile a la persona que necesita suscribirse y detente. Estos cuatro responden por más que crear: una restauración desde el archivo, move --board al tablero de otra persona (la tarjeta y todo lo que contiene cuentan contra ellos), una importación y welcome.
• No account here uses that address… al compartir — este servidor no crea cuentas para las personas con las que compartes cosas. Un administrador debe invitarlos.

En un servidor donde las personas solo ven a aquellos con quienes comparten algo, alguien que esperabas encontrar y no puedes probablemente no ha compartido nada. No ha sido eliminado, y asignarles una tarjeta no funcionará hasta que se comparta algo.

Una tarjeta solo se puede asignar a alguien que pueda abrirla. user … not found en un asignado significa exactamente eso, tenga o no una cuenta — comparte el tablero con ellos primero (la configuración de Compartir del tablero en el navegador), o pídele a la persona que lo haga.

Flujo de trabajo

1. Encuentra el tablero y su estructura primero: slipdock boards, luego slipdock board <board> o slipdock columns <board> y slipdock tags <board>. Los tableros y columnas aceptan un id o un nombre sin distinción de mayúsculas y minúsculas, así que slipdock board "lanzamiento de producto" funciona. Cada tablero también tiene un código — su nombre corto: único, seguro para URL, de máximo 10 caracteres, tomado del nombre del tablero y editable ("QVM V1 Remediation" es qvm-v1-rem). Está en la columna CODE de slipdock boards y en el campo code de --json, y <board> lo acepta en cualquier lugar: slipdock board qvm-v1-rem, slipdock add qvm-v1-rem "...". Prefiérelo al nombre: es inequívoco y sobrevive a renombraciones, y úsalo al nombrar un tablero de vuelta al usuario. slipdock new-board <name> [--code C] establece uno explícitamente; si se omite, se genera uno a partir del nombre. Un tablero también tiene una tecla de acceso directo — uno o dos caracteres que saltan a él en la aplicación web (presiona b, luego la tecla). Es la columna KEY de slipdock boards y el campo shortcut de --json, y se establece con --shortcut K en new-board o set-board. No es una forma de dirigirse a un tablero en la línea de comandos; el código sí lo es.
2. Lee antes de escribir. slipdock card <id> muestra todo: descripción, banderas, etiquetas, ids de elementos de la lista de verificación, comentarios.
3. Usa --json cuando necesites analizar la salida (ids, filtrado, recuento). La salida normal es para mostrar al usuario.
4. Prefiere archive a delete. Eliminar es permanente. Pregunta antes de eliminar cualquier cosa que el usuario no haya pedido explícitamente eliminar. Un tablero completo también se puede archivar (slipdock archive-board <board>), que no es lo mismo que archivar una tarjeta y está mucho más lejos de tu competencia: quita el tablero del índice del usuario, su selector de tableros y su añadido rápido. Nunca archives ni reordenes un tablero a menos que el usuario haya pedido ese tablero por nombre.
5. Di lo que está pasando mientras sucede. El trabajo que dura más de una breve sesión recibe slipdock comment <id> ... en cada hito — y slipdock edit <id> --percent N en lugar de un único informe al final. Una tarjeta en progreso sin un comentario más reciente que el movimiento se lee como abandonada para quien la observa.
6. Informa los ids de vuelta al usuario (#42) para que puedan encontrar tarjetas en la interfaz de usuario. @handle (el correo electrónico de alguien antes del "@") en un comentario o descripción envía un correo a esa persona.