CLI
Un solo binario estático. Los comandos centrales:
synsema init [dir] # scaffold: hello.syn (tour del lenguaje + test), .env.example, .gitignore
synsema init [dir] --synfide # + instala el framework Synfide (workflows durables, bandeja de
# aprobaciones, kv persistente), fijado a su ultimo release:
# sha256 por archivo, synfide/VERSION registra el tag, re-ejecutar
# actualiza (solo archivos del framework — los tuyos jamas se
# pisan, y un archivo del framework que VOS editaste tampoco: la
# version nueva queda al lado como <archivo>.new con aviso fuerte),
# mas un app.syn de arranque y su suite de tests
synsema run program.syn # ejecutar (sale cuando el programa termina)
synsema test program.syn # correr bloques `test` (un archivo o un directorio)
synsema check program.syn # solo parsear — sin ejecutar (rápido)
synsema serve program.syn # quedarse vivo para HTTP / crons / agentes
synsema repl # REPL interactivo
synsema conform --swarm app.syn # dump de estado post-corrida (blackboard + agentes) en JSON
synsema daemon start app.syn # daemon en background (ver Deploy)
synsema llm status # config LLM resuelta + diagnóstico (--json para scripting)
Re-correr init es seguro — y repara
init nunca decide por la mera existencia. Cada archivo que administra se clasifica por
procedencia:
| Su contenido | Qué pasa |
|---|---|
| idéntico a la versión actual | ya está al día — no se toca |
| idéntico a alguna versión anterior publicada | actualizado (estaba sin ediciones tuyas) — seguía de fábrica, recibe la nueva |
| no coincide con ninguna versión publicada | es tuyo: se conserva, y la versión nueva queda al lado como <archivo>.new |
Nadie escribe a mano un archivo byte-idéntico a un release viejo, así que coincidir es prueba
suficiente de que no hay trabajo tuyo que proteger. Eso es lo que permite que un proyecto que
venía salteándose upgrades se ponga al día en vez de quedar congelado — y con --synfide,
re-correr también repara un scaffold con archivos borrados o desfasados, incluso cuando
synfide/VERSION ya nombra el último release (engine v0.5.9+; antes, existir alcanzaba para
considerarlo tuyo).
Qué cubre el .env.example
El .env.example generado viene comentado sección por sección: los pares de provider LLM
(provider + SU key), los techos del host que el programa no puede subir
(SYNSEMA_SPEND_CEILING y el techo por identidad SYNSEMA_SPEND_CEILING_PER_IDENTITY), los
knobs de aprobación humana y, al final, tus propios secretos — los que nombra tu código:
JWT_KEY para jwt_sign, CAPTOKEN_ROOT_KEY para captoken_mint (atenuar no necesita
clave, por eso un subagente delegado nunca la ve) y AGENT_SIGNING_KEY para http_sign (que
además necesita require sign("AGENT_SIGNING_KEY")). El nombre que elegís es el scope de la
capability, así que agregá los tuyos con el mismo patrón. Ver Secretos
synsema llm status
Imprime la configuración LLM que el runtime va a usar de verdad — cada valor con su fuente
(environ / .env / default), la key solo como presencia (jamás valores, prefijos ni
longitudes), qué archivo .env se cargó, y un aviso si hay varios binarios synsema
pisándose en el PATH. Cuando está offline nombra la variable exacta que falta — incluida la
pista "hay una clave bajo DEEPSEEK_API_KEY: ¿la guardaste bajo la variable equivocada?".
No toca la red. Exit 0 = vivo, 1 = offline (scripteable: `synsema llm status && synsema
serve app.syn`). Referencia completa de knobs: Provider config.
Flags útiles
| Flag | Comando | Efecto |
|---|---|---|
--flat | run | parsear un archivo .fsyn (documento plano) |
--explain | run | reporte rico de error en stderr (contexto, call stack, sugerencias) |
--format json | run --explain | diagnósticos estructurados para tools/agentes |
--provider <name> | run | forzar el proveedor LLM (anthropic/openai/minimax/deepseek) |
--sandbox | run / test | techo del host stdout,time — ejecutar código no confiado (ver Capacidades) |
--cap-set "<lista>" | run / test | techo del host a medida (name o name=scope); mutuamente excluyente con --sandbox |
--env-file <path> / --no-env-file | todos | override / desactivar la carga del .env |
--port / --domain / --tls-auto / --bind / --secure | serve | knobs de deploy (ver Deploy) |
REPL
synsema repl abre una sesión interactiva: cada línea es una sentencia top-level, y el estado persiste entre líneas (un let de una línea se ve en la siguiente). Los resultados se muestran con print/show — las expresiones peladas se evalúan pero no se ecoan:
$ synsema repl
>>> let who be "repl"
>>> show "hola " + who
hola repl
>>> print(type_of(who))
text
Salís con Ctrl+D (Ctrl+Z y Enter en Windows). También funciona no-interactivo — pipeá sentencias (printf '...' | synsema repl) para scriptear chequeos rápidos.
Exit codes
0 al tener éxito; 1 ante un error de parseo, un error de runtime, o si algún agente spawneado terminó en ERROR. El run plano imprime la línea estable Runtime error: file:line:col: msg; agregá --explain para el reporte rico. (Para medir exit codes en una shell, no pipees antes de echo $? — redirigí.)