Operación
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 # sin ejecutar: parse + resuelve todos los `use` + valida los templates de render("…")
synsema serve program.syn # queda vivo para HTTP / crons / agentes (--watch = reinicia al cambiar un .syn)
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 e Identidad de agentes.
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 |
--watch | serve | loop de dev: reinicia ante cualquier cambio de .syn (templates/estáticos ya se recargan por request) |
--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í.)