@supen-ai/cli

Supen CLI for bootstrapping a local Supen daemon, managing agents and skills, and chatting with your local runtime from the terminal.

Install

npm install -g @supen-ai/cli

After install, the binary is available as:

supen

Quick Start

The easiest first run is:

supen bootstrap

That walks through initial setup, writes ~/.supen/config.yaml, and prepares the local daemon/service setup.

If you want to configure models manually instead:

supen model add minimax <api-key>
supen model set minimax:MiniMax-M2.7
supen doctor

Common Commands

Interactive REPL

Run supen with no arguments to open the interactive chat REPL:

supen

One-shot Chat

supen chat "hi"
supen chat --agent web-agent --thread <thread-id> "continue"
supen chat --json "status"

Daemon Management

supen update
supen daemon install
supen daemon status
supen daemon logs --lines 100
supen daemon update

Remote Codex Computer Enrollment

When app.supen.ai generates a remote computer claim, paste the generated command on a machine that already has codex installed and authenticated:

curl -fsSL https://app.supen.ai/install.sh | /bin/sh -s -- --claim '<one-time-claim-token>'

--hub-url is optional for production because computer enroll defaults to https://hub.supen.ai. The legacy --gateway-url flag remains supported for existing scripts. The hosted installer downloads a private Node 22.22.0 runtime into ~/.supen when the system Node is too old, then uses @supen-ai/[email protected] with the host runtime to configure Codex app-server transport and start the daemon as a user service with the existing Codex login on that machine.

Run supen update on an enrolled computer to refresh the installed daemon package and restart the user service without repeating enrollment.

Health Checks

supen doctor
supen doctor --fix
supen doctor list
supen doctor run
supen doctor run --fix

supen doctor reports setup issues without changing the machine. supen doctor --fix also applies supported repairs, including canonicalizing the Hub URL, creating local Supen directories, and reinstalling/restarting the host daemon service.

Models

supen model list
supen model add openai <api-key>
supen model set openai:gpt-4.1
supen model remove openai

Skills

supen skills list
supen skills install <git-url-or-name>
supen skills install tiwater/skills/ux-design
supen skills install tiwater/skills --path skills/ux-design
supen skills enable <name>
supen skills inspect <name>

Plugins

supen verify
supen evolve
supen plugin list
supen plugin verify lucid
supen plugin verify /path/to/knowledge-root/plugins/lucid
supen evolve lucid --json
supen evolve lucid --output /path/to/evidence
supen evolve lucid --run-tests

verify defaults to the current mounted plugin when exactly one plugin is mounted. plugin verify resolves the argument as a mounted plugin name first, then as a path. For a mounted knowledge root like lucid-docs/plugins/lucid, lucid is the plugin name and scenarios/ remains the plugin's requirement/evaluation context. Verification runs the plugin validators under plugins/<name>/tests/, discovered plugin test suites, and artifact checks, then publishes evidence, runner stdout/stderr, an artifact index, and generated outputs under ~/.supen/tasks/task-knowledge-evolve-* without writing a separate evolution round.

evolve is knowledge-context scoped, not plugin-scoped. When a focus is provided, Supen uses that mounted plugin to resolve the surrounding knowledge root and then writes promotion evidence plus knowledge issues to .supen/evolution/ unless --output is provided. With one mounted plugin, supen evolve can infer the current knowledge root; otherwise pass a plugin name or path as the focus.

knowledge test and knowledge evolve remain as legacy path-based aliases for existing scripts. New automation should prefer supen verify for plugin checks and supen evolve for knowledge-context evolution.

Agents and Threads

supen agent list
supen agent create research-agent
supen thread list
supen thread show <thread-id>

Config

supen config list
supen config get default_model
supen config set gateway.url https://gateway.example.com
supen config delete gateway.url

For Codex app-server automation that must send private work-item data to a Supen-controlled hub, the daemon passes trusted data hosts into Codex's managed network config. hub.supen.ai is trusted by default, and gateway.supen.ai remains trusted for compatibility. Override or extend the list with either CODEX_TRUSTED_DATA_HOSTS or:

codex:
  trusted_data_hosts:
    - hub.supen.ai

Files and Paths

Supen CLI uses the local Supen home directory:

• config: ~/.supen/config.yaml
• auth: ~/.supen/auth.json
• agents and workspaces: ~/.supen/agents

Isolated environments (dev vs test)

The local daemon stores state under SUPEN_HOME and now also reads:

• SUPEN_DAEMON_CONTAINER_NAME (default: supen-daemon)
• PORT (default: daemon port from config or 2756)

Example dev profile:

SUPEN_HOME=$HOME/.supen-dev \
PORT=2756 \
SUPEN_DAEMON_CONTAINER_NAME=supen-daemon-dev \
supen daemon install

Example isolated test profile:

SUPEN_HOME=$(mktemp -d) \
PORT=3760 \
SUPEN_DAEMON_CONTAINER_NAME=supen-daemon-test \
supen daemon install

Optional helper scripts are available:

./scripts/supen-dev.sh daemon install
./scripts/supen-test.sh daemon install

Typical Local Flow

supen bootstrap
supen doctor
supen daemon status
supen

Or, for scriptable use:

supen chat --json "summarize the current project"

Help

Every command supports --help:

supen --help
supen chat --help
supen daemon --help
supen skills --help

Source

• repo: https://github.com/tiwater/supen
• issues: https://github.com/tiwater/supen/issues