CLI Reference

Sigil’s CLI is built on bunli and runs via Bun.

sigil up [name]

Start an environment from a config file.

Argument	Description	Default
name	Instance name	"default"

Flag	Description	Default
-c, --config	Path to config file	"sigil.config.ts"

Behavior:

1. Checks if an instance with this name is already running. Errors if so.
2. Dynamically imports the config file (must export an Environment as default)
3. Writes instance state to .sigil/instances/<name>.json
4. Starts all entities sequentially via env.up()
5. Keeps the process alive until interrupted

Signal handling: On SIGINT (Ctrl+C) or SIGTERM, calls env.down(), removes the state file, and exits cleanly.

Exit codes:

• 0 — Clean shutdown
• 1 — Error (instance already running, config load failure, startup failure)

sigil down [name]

Stop a running environment.

Argument	Description	Default
name	Instance name	"default"

Behavior:

1. Reads instance state from .sigil/instances/<name>.json
2. If the process is dead, cleans up the stale state file
3. If alive, sends SIGTERM to the sigil up process
4. Polls for process exit (500ms intervals, 30s timeout)
5. Falls back to SIGKILL if the process doesn’t exit
6. Removes the state file

The down command does not re-import the config. It signals the up process, which handles its own teardown.

sigil status [name]

Show running instances.

Argument	Description	Default
name	Instance name (optional)	Show all

Output format:

Instance: default (PID 12345, running, started 5m ago)
  Config: /path/to/sigil.config.ts
  Entities:
    db                   running
    backend              running
    frontend             running

Status values:

• running — PID is alive
• stale — PID is dead (state file is automatically cleaned up)

sigil init

Initialize a new Sigil project in the current directory.

Note

This command is currently a stub and will be implemented in a future release.

Global Flags

Flag	Description
--help	Show help
--version	Show version