astrid-cli

The terminal frontend for the Astrid OS.

In the OS model, this is a shell. It does not run agents, call LLMs, enforce security policy, or own state. It spawns the kernel daemon as a background process, connects over a Unix domain socket, and renders streaming events in a ratatui TUI. Kill the CLI. Reconnect. Pick up where you left off. The daemon owns the session. The CLI is disposable.

Architecture

Three companion binaries work together:

Binary	Crate	Role
`astrid`	astrid-cli	Terminal frontend (TUI, REPL, capsule management)
`astrid-daemon`	astrid-daemon	Background kernel process (boots kernel, loads capsules, serves IPC)
`astrid-build`	astrid-build	Capsule compiler and packager (Rust, OpenClaw, MCP)

The CLI discovers companion binaries in the same directory as itself, falling back to PATH. It never links the kernel directly — all communication is over the Unix domain socket via length-prefixed JSON.

Quick start

cargo install --path crates/astrid-cli
cargo install --path crates/astrid-daemon
cargo install --path crates/astrid-build

astrid init
astrid chat

Commands

Chat & sessions

Command	Description
`astrid`	Start an interactive chat session (default command)
`astrid chat`	Same as above. `--session <UUID>` to resume a specific session.
`astrid session list`	List persisted sessions
`astrid session info <ID>`	Show session details
`astrid session delete <ID>`	Delete a session

Daemon lifecycle

Command	Description
`astrid start`	Start a persistent daemon (detached, no TUI). Survives CLI disconnect.
`astrid status`	Show daemon PID, uptime, connected clients, loaded capsules.
`astrid stop`	Gracefully shut down the running daemon.

When you run astrid chat without a running daemon, an ephemeral daemon is spawned automatically. It shuts down on idle after the last client disconnects. Use astrid start for a persistent daemon that serves multiple frontends (CLI, Discord, web).

Capsule management

Command	Description
`astrid capsule install <source>`	Install from local path, GitHub URL, or registry. `--workspace` for workspace-level.
`astrid capsule update [target]`	Update one or all capsules from their original source.
`astrid capsule list`	List installed capsules with capability metadata. `-v` for full details.
`astrid capsule deps`	Print the capsule dependency graph.

Build & init

Command	Description
`astrid build [path]`	Compile and package a capsule. Delegates to `astrid-build`.
`astrid init`	Initialize a workspace in the current directory.

Daemon connection flow

Check for existing daemon (socket probe at ~/.astrid/run/system.sock)
If running → connect and perform handshake
If not running → spawn astrid-daemon --ephemeral, poll readiness sentinel, connect
If stale socket (connection refused) → clean up, respawn

Global flags

Flag	Description
`-v, --verbose`	Enable debug-level logging
`--format json`	Switch to NDJSON output for scripting. Interactive prompts are auto-denied.

Development

cargo test -p astrid-cli

License

Dual MIT/Apache-2.0. See LICENSE-MIT and LICENSE-APACHE.

astrid 0.5.0