Referencia de comandos
Actualizado 2026-10-10
Todos aceptan --json y --help (ghosty skills --help y ghosty help skills enseñan el uso y los ejemplos de ese comando). <id> es un agente: su nombre (ghosty agents get pia-0, sin importar mayúsculas) o su id (sale en ghosty agents ls). Si varios se llaman igual, gana el del espacio de ghosty use; si aún son varios, el CLI enseña los ids para elegir.
Regla de nombres (como gh): sustantivo y luego verbo (ghosty cards show, ghosty boards create); prender o apagar algo es enable / disable (ghosty skills disable <id> pdf-doc); on / off sólo como valor de una opción (--sponsor on). Las formas viejas (board, skills on|off, --on/--off, --vence) siguen funcionando y avisan cuál es la nueva.
Sesión
Agentes
agents get enseña el env del agente; los valores con cara de secreto (…KEY, …TOKEN, …SECRET) salen como •••.
agents box dice qué máquinas lo atienden y, con --check RUTA (se repite) o --contains RUTA=TEXTO, si traen lo que esperas. Sirve tras un cambio de imagen: si sale ✗, --recycle y verifica después de un turno. En Ghosty · Lite y Goose se usa agents restart.
create da de alta un agente de tu cuenta (sin espacio de trabajo) y devuelve su id. Sin --engine usa Claude; sin --model, el default del motor. Un motor o modelo que no existe se rechaza (también sin --engine) y el error lista los válidos; ghosty engines ls --models los enseña antes.
--env K=V,K2=V2 pone variables en la máquina del agente, en create o en set; K= la borra. La más útil: GHOSTY_THINKING_EFFORT (off · low · medium · high · max) fija cuánto piensa el modelo en Ghosty · Lite.
Conectar Drive (u otro conector) en tu cuenta no le da acceso a ningún agente: cada uno lo recibe con --connect <conector> o en su ficha → Conectores. Sólo el dueño puede darlo.
set cambia sólo lo que le pases. El prompt y el modelo se aplican desde el siguiente turno. Con --engine cambias el motor; --model es entonces un modelo del motor nuevo. En Claude el esfuerzo es --env FLEET_EFFORT=low|medium|high|xhigh|max; sin él va en medium. Codex, DeepSeek, Goose y DeepAgents están deprecados: usa Claude, Ghosty · Lite o Gemini.
Demo público: agents demo
Una liga /p/<nombre>-<código> para que cualquiera pruebe tu agente sin cuenta, tal cual lo armaste (su máquina, sus skills, su motor), pagado por ti. Con «Quedármelo» la persona crea su cuenta y se lleva su copia, con la conversación y los archivos de la prueba.
Sin opciones sólo enseña el estado. La salida trae las pruebas, mensajes y copias (cuántas con tu llave) y, si el agente no contestó a un visitante, el último motivo.
Widget web: agents embed
Una burbuja de chat con tu agente en tu sitio, con una línea de código. Sólo carga en los dominios que pongas; cada visitante tiene su conversación, aislada, y habla como cliente. Detalle en .
La salida trae también el snippet de React (npm i @ghostystudio/widget + <GhostyWidget token="emb_…" />); en --json, en el campo react ({install, code}).
Probar un demo y ver qué pasó: demos
demos try cuenta contra los topes del demo (mensajes por visitante y por IP al día) y sale en sus números y en el CRM. demos history enseña turnos, mensajes, adjuntos, entregas y clones; es sólo para el staff de Ghosty: el dueño ve números (agents demo), no los chats de sus visitantes.
El agente como archivo
ghosty agents export saca toda la configuración de un agente a un YAML (compatible con las recetas); ghosty apply deja a un agente como dice el archivo, enseñando antes el plan.
- Lo que el archivo no menciona no se toca; los campos que trae quedan exactos.
- Las listas (bases, documentos, compartidos, skills propias, variables de env) agregan y cambian; quitar exige
--prune(sin él salen con!). - Los secretos nunca salen: se exportan como
${NOMBRE}. ConNOMBREen tu entorno se cambia; si no, se conserva el valor de hoy. - Antes de aplicar se guarda la versión actual del agente (Versiones, en la web).
applyno mueve un agente de espacio.
Configurar un agente
Todo agente tiene máquina y disco propios: archivos, skills y MCP funcionan con cualquier motor. En los de pool (Claude, Codex, DeepSeek, Gemini) entran solos en el siguiente turno; en Ghosty · Lite y Goose las skills nuevas entran con agents restart (needsRestart en agents get).
Archivos
Prompt derivado
Un agente puede heredar el prompt de otro con una capa de ediciones: la sucursal de una tienda que usa el prompt de la matriz, cambiando nombre, horario y catálogo. Cuando cambia el de la base, el derivado se regenera solo.
- Las ediciones van en orden y cada una tiene que encontrar su sitio. Si la base cambió justo ahí, el derivado se queda con su prompt anterior y
agents doctorlo marca (prompt.base). --dry-rundice si todas aplican (--out FILEescribe el resultado).--prompt-base nonesuelta la liga y conserva el prompt de hoy.- Mientras esté ligado, su prompt no se edita a mano (409): se cambia la base o la capa.
Parchar el prompt
Para cambiar un pedazo del prompt sin reescribirlo entero (y sin pisar lo que alguien más cambió en medio), con el mismo formato de capa:
- Se aplica en el servidor, sobre el prompt de ese momento: no hace falta bajarlo con
get --prompt-outy volver a subirlo. - Si una edición no encuentra su lugar, no cambia nada (409 con cuál fue).
--prompt-patchy--prompt-appendjuntos: primero las ediciones, luego el texto. - Queda en la bitácora (
agent.prompt_patch). No aplica a un prompt derivado: ahí se cambia la base o la capa.
Skills
skills rm guarda la copia en ~/.config/ghosty/trash/ e imprime el comando que la restaura.
skills templates lee una máquina viva (corre un turno antes) y lista lo que ve pdf-doc: agente:<skill> o casa. Una plantilla propia es <skill>/pdf-templates/<nombre>.html en cualquiera de sus skills; con el mismo nombre le gana a la de casa.
Servidores MCP
Una llave por usuario final: en un MCP http, una cabecera puede llevar ${turn.token}
("Authorization": "Bearer ${turn.token}"). Cada turno de message-stream o turns manda su
turnToken y gs lo pone sólo en ese turno, a través de su proxy: el token nunca entra a la caja ni
se guarda. Un turno sin turnToken en ese agente falla con error. No vale en sse, stdio, la URL
ni en agentes ACP.
Cotizar con la tool de casa: IVA y catálogo
La tool cotizar hace las cuentas, el folio y el PDF; el agente sólo pone los renglones. El IVA de cada renglón sale de la configuración del agente, en este orden:
- Si la llamada trae
iva_pct, ésa para todo. - Con
solo-factura=truey sinfactura: trueen la cotización: 0. - Si la categoría del renglón tiene regla (
iva.GRANEL=16): ésa. - Con
iva-incluido=true(los precios ya lo traen): 0. - Si no:
iva(16 por default).
La categoría sale del catálogo del agente (--catalog), no del modelo; sólo si el producto no está en el catálogo cuenta la que mande el agente. Si los renglones llevan tasas distintas, el PDF lo desglosa («IVA (GRANEL 16%)»). Un agente con su propia skill cotizar no usa esta tool: guardar esa skill la apaga.
Revisar un agente: agents doctor
Como brew doctor: sólo enseña lo que hay que atender, cada hallazgo con el comando que lo arregla, y sale con 1 si hay un problema (sirve de compuerta en un script). --verbose enseña también lo que pasó.
Revisa: skills que podrían dispararse con lo mismo (dos de cotizar encendidas a la vez), skills que el prompt nombra (skill \cotizar`, .claude/skills/cotizar/) y el agente no tiene o tiene apagadas, una skill propia con el nombre de una tool de casa que sigue encendida (el modelo puede usar la genérica), tools que el prompt nombra y no existen o no tienen permiso, tablas de escritura desde clientes que ya no existen, db_/doc_` en el prompt sin nada concedido y turnos que fallaron en las últimas 24 h.
Bases de datos
queryes de sólo lectura;--writepermiteINSERT/UPDATE/DELETE/DDL.--arg Vda el valor de cada?, en orden (se repite).importreemplaza las filas de cada tabla (idempotente);--appendlas agrega en vez de reemplazar y--tables a,bcopia sólo esas.--dry-runenseña el plan (+crea,~reemplaza N → M filas) y no cambia nada. Si la base es compartida con agentes que ya escriben en gs (cotizaciones, folios), avisa de las filas que sólo existen en gs y pregunta antes de borrarlas.exportbaja una copia: sin--table, la base entera como SQLite (todas las tablas, con sus filas); con--table, esa tabla en CSV UTF-8.--outdice dónde guardarla. Usa tu sesión, no el tokengat_del agente, y queda en la bitácora. Las mismas descargas están en la página de cada base (/app/datos?tab=dbs→ la base → .sqlite / tabla.csv).dbes alias dedbs, ydbs sqldedbs query.
Fotos del catálogo
Las fotos de un catálogo deben vivir en ligas permanentes (img.ghosty.studio): las de EasyBits o de la web del cliente caducan o cambian, y WhatsApp deja de mandarlas.
importavisa si reemplazar una tabla regresaría ligas permanentes a ligas de fuera, y te da la bandera exacta.photos putsólo acepta JPEG, PNG o WebP de hasta 10 MB;--dry-runlista las claves que no tienen fila y los archivos que no son imagen. La columna esimagen_urlsalvo--column.- En la web (
/app/dbs, pestaña Tablas) ves los mismos conteos, el botón «Hacer permanentes» y puedes arrastrar una foto a una fila.
Documentos
<base> y el documento aceptan el id o el nombre. Un token de agente (gat_…) sólo ve lo concedido y no puede concederse nada.
Un documento es uno solo aunque lo usen varios agentes: replace sube una versión nueva que conserva el nombre (sólo la extensión sigue al tipo), los accesos y a todos los agentes que lo usan, así que el prompt que lo nombra no se rompe. La versión anterior queda en el historial (se guardan 20). Con un token de agente, replace y restore sólo funcionan si el agente tiene «Puede actualizarlo» (grant --write).
Turnos
turns grep busca en el texto de las conversaciones (no en los pasos ni las tools) y devuelve cada coincidencia con su turno, para abrirlo con turns show. En la columna «resumed», «1.er turno» es el primer turno de una sesión nueva del SDK: no es pérdida de memoria.
--errors es lo mismo que --status error. --since acepta 30m, 1h, 2d o una fecha ISO; --limit es 20 por default (máximo 500).
turns show enseña primero lo que entró (in) y lo que contestó (out), en cualquier motor y canal (grupos de WhatsApp incluidos). Luego responde «¿en qué se fueron 4 minutos?»: la línea de tiempo del turno (+12.3s Bash office-reader … 8.1 s), las tools más lentas y el total de llamadas al modelo y tokens de salida. Esa parte sale del transcript del motor, así que sólo existe en los de pool (Claude, Codex, DeepSeek, Gemini), no en Ghosty · Lite ni Goose.
Canales de WhatsApp
Encender un número hace que el agente les conteste a clientes reales: pide escribir los últimos 4 dígitos (o --yes). Un número tiene un solo agente: encenderlo se lo quita al otro.
Los grupos son del WhatsApp personal pareado al agente (no de WhatsApp Business): en cuáles contesta y con qué rol. equipo = gente de la casa (escribe en bases, tools de admin); cliente = como cualquier cliente.
<grupo> es su nombre o su jid. Encender un grupo confirma (o --yes): el agente empieza a contestar ahí.
--wake: mention (default al encender un grupo) abre turno sólo si mencionan al agente con @, escriben su nombre o le responden a un mensaje suyo; lo demás le llega como contexto en su siguiente turno. all contesta cada mensaje (los grupos importados y los creados con create).
¿Quién contestaba este número?
Si un número o una página quedó sin agente, la columna «last answered by» dice qué agente lo contestó por última vez y cuándo (sale de los turnos de gs), para regresárselo:
Traer un número de otro lado
Para migrar un agente de EasyBits (o de un droplet) sin volver a dar de alta el número:
--answerno tiene default:oncontesta a clientes reales;offsólo registra. Formmy únicamente reenvía si su canal está encendido: cononse enciende; conoff, sólo si agregas--forward(el plan avisa si gs no va a ver las conversaciones).- Lo hace el dueño, un admin del agente o el staff de Ghosty. Si el dueño del número en Formmy tiene otro correo, sólo el staff.
historyva después delinky no duplica: córrelo antes del corte y otra vez justo en él. No dispara avisos de «lead nuevo».historytambién copia a gs los archivos (fotos, PDF, audios) y el resumen dice cuántos se copiaron y cuántos fallaron. Formmy los borra a los 7 días: trae el número dentro de esa semana. Los que fallaron se reintentan con--media, que no toca tarjetas ni mensajes; con--dry-rundice cuántos faltan.import: apaga antes el WhatsApp en EasyBits sin cerrar sesión (dos conexiones con las mismas llaves se tumban; cerrar sesión las invalida).--own-number no= es el número de una persona: sólo su chat consigo misma cuenta como del dueño. Borra el archivo al terminar: son las llaves de la cuenta.
Tablero
resume no contesta solo (el despertar que Formmy manda al reanudar se ignora); para eso está reply, que sólo sirve en WhatsApp Business y si el número lo contesta ese agente. pending marca y nunca contesta: las pausadas, las escaladas, las que salieron de la ventana de 24 h de WhatsApp (Meta sólo acepta plantillas), las que sólo traen una reacción, las que no son de WhatsApp Business y las de números sin agente. pause, resume y reply quedan en la bitácora.
El tablero es del espacio: un agente compartido contigo no te da su tablero; el dueño tiene que agregarte al espacio. Se necesita al menos un filtro (--integration, --column o --before).
Credenciales
Una llave nunca se acepta como argumento: se quedaría en el historial del shell. creds es alias de credentials.
Conectores
Son los mismos de /app/connectors y la app. Los de llave con varios campos (Odoo, WooCommerce…) los pregunta uno por uno; los secretos sin eco y nunca como argumento.
Confirmaciones
agents rm, files rm, skills rm, credentials rm, board archive, reemplazar filas con dbs import y channels whatsapp enable preguntan antes de actuar. Sin terminal (un agente de código, CI) nunca esperan respuesta: agrega --yes, o salen con 2 y el comando exacto para reintentar.
Platicar con un agente
Turnos de prueba
--waba pasa por el mismo camino que un cliente real de WhatsApp Business (contexto heredado, regla de precios, tablero, voz) y no manda nada: ni mensaje, ni nota de voz, ni link de pago. Enseña todo lo que habría salido, también lo que mandan las tools: 📍 ubicación, 📄 archivos, 🎤 voz, ↩️ citas, 🔘 botones, 👤 contactos y reacciones. Con --as-formmy el adjunto recorre lo mismo que uno real: proxy con credencial, copia en gs y transcripción; al final dice si la copia llegó. --replay corre desde tu máquina y escribe replay.json después de cada paso; si Ghosty se despliega a media corrida espera el Retry-After y sigue, y --resume retoma una corrida cortada.
Conversaciones
try es para probar configuración; chat usa las conversaciones reales del agente, las mismas que ves en el panel y en la app.
Programar turnos
El agente trabaja solo a la hora que le digas: cada corrida cae en una conversación y te avisa en el teléfono (app de iOS o Mac). Si su respuesta es exactamente OK, no avisa; úsalo para un «revisa y avísame sólo si…».
Sin --conversation se abre una conversación nueva (con --title, lleva ese nombre). Reglas: repetición mínima cada 15 minutos, --until obligatorio al repetir, como mucho a 30 días, y hasta 5 pendientes por conversación.
En una conversación de un canal (--conversation waba:…, wa:<jid> de WhatsApp personal —un grupo o un chat— o messenger:…) la respuesta sale por ese canal; una respuesta «OK» no se manda. En WABA sólo dentro de la ventana de 24 h; en WhatsApp personal, si el número del agente está conectado.
En un hilo de Teams
A esa hora el agente contesta en el room (o en el hilo: el número es el id del mensaje con que empieza) como si alguien lo mencionara, con la memoria de ese room. Hace falta que esté activo en el Teams del espacio y que seas miembro. Sin hilo, publica en el room. --every todavía no va con --teams.
Tu cuenta
Uso
plan apply lo puede correr el staff o el dueño del espacio si no tiene suscripción (con suscripción, el plan nuevo entra al pagarse la factura). Sin espacio, ambos usan el de ghosty use.
Con --json trae plan.name, week.pct y month.pct (de 0 a 1; month.pct es null si tu plan no tiene tope mensual), sus resetsAt, creditMxn (saldo de recargas) y exhausted (true si ya no te queda uso). Cambiar de plan o recargar: .
Espacios
Bolsas de tokens, renovación y slug de un espacio. Leer las bolsas lo puede el dueño; cambiarlas, renovar y renombrar es del staff de Ghosty (queda en la bitácora del espacio).
Un traspaso sólo cambia el dueño: el espacio, sus agentes, sus skills y su historial se quedan igual. Los documentos, bases, tableros y números que usan sus agentes pasan a la cuenta nueva; lo que también usa un agente de fuera del espacio se queda y la simulación lo avisa. --copy-keys copia las llaves de proveedor y los conectores (MercadoPago, Skydropx…) que le falten al dueño nuevo.
Archivar no borra nada: el espacio deja de salir en /app y en ghosty spaces ls, y sus agentes, datos e historial se quedan. Lo puede el dueño o el staff; queda en la bitácora (workspace.archive / workspace.restore) y se deshace con ghosty spaces restore <espacio>.
Una bolsa mensual (default) se recarga cada periodo del espacio; una de carga única (--recurring off) cuenta todo lo gastado desde que se creó y, al acabarse, se acabó. Con --hard-cap on (default) los turnos se frenan al 100 % con «se acabó el saldo»; con off sólo se cuenta. Un agente sin bolsa gasta del saldo del espacio.
Bitácora
Quién cambió qué: el «Guardar» de la ficha, los cambios de canal, pausas y respuestas desde el CLI, parches del prompt, traspasos, staff que entra o sale y «entrar como». El staff de Ghosty ve todo; cualquier otra cuenta, sólo lo de sus espacios y sus agentes. El token gat_ de un agente no la lee.
Fábrica
Los pedidos de la Software Factory de un espacio (viven en su Teams). Leer pide ser miembro; renombrar, dueño, admin o staff (queda en la bitácora como factory.run_rename).
runs ls enseña cuánto tardó y costó cada pedido. Para ver en qué se fue el tiempo y el dinero de uno:
- Trabajando: algún rol tenía un turno corriendo. Esperando a una persona: el plan o el PR por aprobar. Lo demás: CI, colas, despliegue.
- Los comandos de 60 s o más salen de la transcripción de cada rol. Los motores ACP no guardan una: salen con minutos y costo, sin comandos.
- El costo incluye el primer turno de
@planen el hilo, antes de que naciera el pedido.
Por qué se atoró o falló (un pedido sano no llama al modelo; el análisis se guarda, --refresh lo rehace). Ver :
Y cómo va la fábrica del espacio:
Pedir ayuda
Soporte es por correo: cada caso tiene su propia dirección de respuesta, así que contestar el correo o escribir aquí cae en el mismo caso. También se lo puedes pedir a tu agente en tu chat: «repórtalo a soporte». El caso lleva tu cuenta, tus agentes y sus errores recientes; no tienes que repetirlos.
En la web: Soporte en el menú de .
Soporte
Para el staff de Ghosty (User.isAdmin): lo que antes era un script en la caja por cada reporte. Leer conversaciones ajenas queda en la bitácora.
conversations archive|rm con --kind test|channel es para el dueño del agente (o staff): rm nunca borra hilos de clientes (--kind channel), que sólo se archivan porque su memoria es la que los sigue atendiendo. --kind personal lo usa cualquiera con acceso al agente y sólo toca SUS propios chats con él, nunca los de otra persona. Lo borrado desaparece también de las apps (iOS, Android) en su siguiente sincronización. push log se registra desde el 1-oct-2026 y se guarda 30 días; desde el mismo día incluye el push de las novedades (kind: novedad), y novedades ls dice cuántos entregó y rechazó FCM. agents ls --user --app enseña también sus teléfonos con la build de la app, y la columna «fetched» de agents doctor --user existe desde el 1-oct. --tools lee el transcript en Tigris (claude-worker) o el historial de la caja (goose, ghosty-lite); nunca con un turno en marcha en ese hilo.
Staff asignado
Un ejecutivo de Ghosty asignado a la cuenta de un cliente ve y opera, con su propia sesión, los agentes de esa cuenta (con y sin espacio), sus documentos, bases y tableros. No ve llaves ni tokens, no toca plan ni cobro, no traspasa ni borra. Sólo el staff asigna; el cliente lo ve como «Tu ejecutivo de Ghosty» en su cuenta. Cada asignación y cada escritura del ejecutivo quedan en la bitácora.
En el panel, el ejecutivo elige «Atendiendo: » en Documentos y bases y en Agentes; es una cookie que se revalida en cada request, nunca otra sesión ni «Entrar como».
Sitios
Los sitios que publican tus agentes, en <slug>.ghosty.page (nadie necesita cuenta propia de nada). sites ls enseña los tuyos: vivos, en pausa y despublicados que aún se pueden recuperar.
Plan Gratis: un sitio se pausa a los 30 días sin cambios (aviso 7 días antes; cada cambio le da otros 30). En pausa su liga enseña «Esta página está en pausa — Reactívala» y no se borra nada. A los 30 días de pausa se despublica (la liga ya no sirve y el slug queda apartado) y su copia se guarda 6 meses más; después se borra de verdad. Reactivarlo en cualquier momento antes de eso lo regresa tal cual, en la misma liga.
Sitios fijos: $49 USD al año o $5 USD al mes ($990 / $99 MXN), incluye hasta 3 sitios. Un sitio fijo no se pausa y va sin la franja «Hecha con Ghosty». ¿Necesitas más? Cada paquete extra suma 3 sitios por el mismo precio. Soltar un sitio, cancelar o un pago fallido lo regresan a la regla Gratis con aviso: nunca se pausa de golpe.
El slug: minúsculas, números y guiones, de 3 a 60, sin guion al inicio, al final ni doble, y no reservado (api, admin, s, www, app, assets, static, dashboard, login). Errores con código: slug_invalid, slug_taken y slug_unsupported (EasyBits todavía no acepta elegir ni cambiar el slug; no cambia nada y sale con 1). Topes: 1 MB por archivo, 8 MB y 40 archivos por sitio.
Navegador
Pide confirmación (--yes para scripts). Para volver a conectar la terminal, copia el comando nuevo del panel de la extensión. Ver .
Partners
ghosty partner le da un agente a cada uno de tus clientes (un solo agente compartido, memoria por cliente). Tiene su propia página: .
Idioma
El CLI habla español si tu sistema está en español (LANG=es_MX…) y en inglés en otro caso; --lang es|en o GHOSTY_LANG lo fuerzan. También traduce al inglés los mensajes del servidor. Con --json las llaves y los códigos no cambian.
Autocompletado
Completa comandos, subcomandos y opciones, y los nombres de tus agentes y espacios (se guardan 5 minutos).
Opciones globales
Un token de agente (gat_…, se genera en la ficha del agente) sólo alcanza a ese agente: sirve para agents get/set/restart, files, skills, mcp y try, pero no para listar agentes ni para chat.