GenosOS ships a single binary entry point. When running from source, use bun genosos.mjs <command>. When installed globally via npm, use genosos <command>.
# From source
bun genosos.mjs <command> [flags]
# Global install
genosos <command> [flags]
Commands
| Command | Description |
|---|
gateway | Start the AI gateway server on port 18789 |
agent | Send a message to the agent from the CLI |
tui | Launch the terminal UI (TUI) |
channels | Manage channel connections |
agents | List and manage agents |
models | List and manage AI models |
vault | Manage the encrypted secret vault |
config | Read and write gateway configuration |
status | Show gateway and channel status |
doctor | Run automated health checks and security audit |
setup | First-time setup wizard |
gateway
Start the gateway server. On first run, an onboarding wizard prompts for an API key and opens the browser automatically.
Flags
| Flag | Description |
|---|
--force | Force start even if the port is already in use |
# Standard start
bun genosos.mjs gateway
# Force start (override port conflict)
bun genosos.mjs gateway --force
agent
Send a message to the agent from the command line. Useful for scripting, automation, and RPC integrations.
bun genosos.mjs agent --message "your message"
| Flag | Description |
|---|
--message | Message text to send to the agent |
--mode rpc | Run in RPC mode (machine-readable output) |
--json | Output response as JSON |
# Send a plain message
bun genosos.mjs agent --message "What's the weather in Madrid?"
# RPC mode with JSON output (for scripting)
bun genosos.mjs agent --mode rpc --json
# Harden security via agent
bun genosos.mjs agent --message "harden security"
tui
Launch the terminal UI — a full-featured chat interface that connects to the running gateway via WebSocket.
Key bindings
| Key | Action |
|---|
Ctrl+L | Open model picker |
Ctrl+G | Open agent picker |
Ctrl+P | Open session picker |
! | Run local shell command |
/compact | Manually trigger TOON compaction |
The gateway must be running before launching the TUI. Start it with bun genosos.mjs gateway.
channels
Manage channel connections. Use this to add, remove, list, and probe channels.
genosos channels <subcommand> [flags]
| Subcommand | Description |
|---|
status | Show status of all configured channels |
add | Add a new channel |
remove | Remove a channel |
list | List all channels |
| Flag | Description |
|---|
--probe | Probe all channel connections for liveness |
# Show channel status with live connection probes
genosos channels status --probe
# List all configured channels
genosos channels list
agents
List and manage agents. Each agent is an isolated execution context with its own workspace and sessions.
genosos agents <subcommand>
| Subcommand | Description |
|---|
list | List all configured agents |
add | Create a new agent |
delete | Remove an agent |
# List all agents
genosos agents list
models
List and manage available AI models and providers.
genosos models <subcommand>
| Subcommand | Description |
|---|
list | List available models and their auth status |
set | Set the default model |
auth | Authenticate a provider (device flow) |
# List all models with auth status
genosos models list
# Authenticate a provider using device flow
genosos models auth login --provider github-copilot
vault
Manage the encrypted secret vault. Secrets are stored with AES-256-GCM (NYXENC1) and never written to disk in plaintext.
genosos vault <subcommand> KEY [VALUE]
| Subcommand | Description |
|---|
set <key> <value> | Store or update a secret |
get <key> | Retrieve a secret value |
list | List all stored secret keys |
delete <key> | Remove a secret |
cat <path> | Decrypt a file to stdout (pipe-safe, no disk write) |
write <dest> [src] | Encrypt and write a file (reads from src or stdin) |
lock | Encrypt all files in the state directory |
unlock | Decrypt all files in the state directory |
status | Show encryption status of the state directory |
keychain-store | Store vault passphrase in macOS Keychain (macOS only) |
keychain-remove | Remove vault passphrase from macOS Keychain (macOS only) |
# Store an API key
genosos vault set STRIPE_API_KEY sk_live_...
# Retrieve a secret
genosos vault get STRIPE_API_KEY
# List all keys
genosos vault list
# Decrypt and read a vault-protected file
genosos vault cat ~/.genosv1/genosos.json
# Check encryption status
genosos vault status
# Migrate passphrase to macOS Keychain
genosos vault keychain-store
config
Read and write gateway configuration. The preferred interface is natural conversation with the agent, but config provides direct programmatic access via config_manage blueprints.
genosos config <action> <path> [value]
| Action | Description |
|---|
describe <path> | Get guidance about a configuration path |
set <path> <value> | Set a configuration value |
get <path> | Read a configuration value |
remove <path> | Remove a value from an array path |
list <section> | List all paths in a section |
# Describe what a config path does
genosos config describe channels.telegram.dmPolicy
# Set a value
genosos config set channels.telegram.dmPolicy pairing
# Read a value
genosos config get gateway.port
# List all paths in the security section
genosos config list security
status
Show the current state of the gateway, channels, agents, and security posture. Output is always read-only and pasteable.
Flags
| Flag | Description |
|---|
--all | Full status output — read-only, safe to copy-paste |
--deep | Probe all channel connections (slower, more accurate) |
--json | Output status as JSON |
# Quick status
genosos status
# Full pasteable status report
genosos status --all
# Deep probe (tests live connections)
genosos status --deep
doctor
Run 7 automated security and health checks. The doctor engine identifies and, where safe, auto-fixes common configuration issues.
Checks performed:
- Gateway bind address (loopback only)
- DM policy (no open-to-all without allowFrom)
- Vault encryption status
- Audit log integrity
- Channel tool restrictions
- Spotlight and Time Machine exclusion
- Auto-lock timeout (vault idle)
Run genosos doctor after any significant configuration change, or ask the agent: “run a security audit”.
setup
First-time setup wizard. Initializes the workspace directory, agent defaults, and configuration file.
You typically do not need to run setup manually — the gateway runs it automatically on first launch. Use it to reinitialize a workspace or change the default workspace path.
Development commands
These commands are available when working from source. They use pnpm as the package manager.
| Command | Description |
|---|
pnpm setup | Install dependencies, build, and build UI |
pnpm gateway:watch | Start gateway with hot reload (dev loop) |
pnpm test:fast | Run unit tests only |
pnpm test | Run all tests (unit + E2E) |
pnpm build | Build for production |
pnpm check | Run lint and format check |
# Clone and install
git clone https://github.com/estebanrfp/genos.git
cd genos
pnpm setup
# Development loop
pnpm gateway:watch
# Run tests
pnpm test:fast # fast (unit only)
pnpm test # full suite
