Setsuna CLI

Setsuna CLI is a lightweight terminal client for the Setsuna Agent OpenAI-compatible gateway.

Phase 1 supports API key login, model discovery, model switching, one-shot prompts, and an Ink-based streaming terminal UI inspired by qwen-code's React terminal layout.

Requirements

• Node.js 20 or newer
• A running Setsuna Agent backend
• A Setsuna proxy API key, for example sk-setusna-...

Usage

pnpm install -g setsuna-cli
setsuna

You can still run it from the source checkout without installing:

cd cli
pnpm start

Common commands:

setsuna auth
setsuna models
setsuna model
setsuna chat
setsuna -p "用一句话介绍 Setsuna Agent"

You can also pass values non-interactively:

setsuna auth --base-url http://127.0.0.1:8000 --key sk-setusna-...

The CLI stores local credentials at:

~/.setsuna/cli/config.json

The file is created with owner-only permissions when possible.

Commands

setsuna auth                  Save API key and server URL
setsuna auth status           Show local auth state
setsuna auth logout           Remove saved API key
setsuna models                List available models
setsuna model [provider:model] Show or change selected model
setsuna chat                  Start interactive chat
setsuna -p "question"         Ask once and exit

Inside chat:

@file       Search and attach a workspace file to the next prompt
$skill      Search and attach a Setsuna skill to the next prompt
/auth       Re-authenticate with a new API key
/workspace  Switch the active workspace root
/model       Change selected model
/plan        Configure automatic plan tracking
/skills      Configure and browse Setsuna skills
/mcp         Show, reload, enable, or disable local MCP tools
/permissions Configure confirmation behavior for file edits
/models      List available models
/open        Open the most recent generated artifact, or a given path
/clear       Clear local conversation context
/status      Show current server, key, and model
/help        Show slash commands
/exit        Leave chat

/quit is accepted as an alias for /exit, and /settings is accepted as an alias for /permissions.

Type @test to search files in the active workspace by filename or path. Use ↑/↓ to choose a match and Tab or Enter to insert it, then send the message. The @file index refreshes while you type and after successful agent file edits, so newly created files can show up without restarting the CLI. Mentioned files are read locally and attached to that prompt as focused context for the agent.

File mention indexing respects root-level .gitignore, .ignore, .qwenignore, and .setsunaignore files. It also skips common large or sensitive paths such as node_modules/, .venv/, dist/, build/, .env, and key files.

Assistant messages that include <think>...</think> are rendered as muted thinking blocks instead of raw XML-like tags, while the final answer remains in the normal message style.

Local Tools

Interactive chat exposes OpenAI-compatible function tools to the selected model:

list_directory       List workspace files
find_files           Find files by name or path
search_text          Search text in workspace files
read_file            Read UTF-8 text files
edit                 Replace exact text in an existing UTF-8 file
git_status           Show Git branch and status
read_diff            Read unstaged or staged Git diff
write_file           Create or overwrite UTF-8 text files
run_shell_command    Run foreground shell commands

All paths are constrained to the active workspace root. list_directory, find_files, search_text, read_file, git_status, and read_diff are read-only and run without confirmation. edit, write_file, and run_shell_command pause the terminal UI and require explicit Y approval before they run, unless file edit confirmation has been disabled with /permissions. Shell commands always require confirmation.

find_files and search_text respect root-level .gitignore, .ignore, .qwenignore, and .setsunaignore files, plus common generated or sensitive paths. search_text uses rg when available, falls back to grep when available, and finally uses a built-in Node.js scanner so the tool still works across macOS, Linux, Windows, and minimal environments.

For existing files, the agent is instructed to use edit instead of shell scripts or full-file rewrites. Existing files must be read with read_file before edit or write_file can modify them, and the CLI rejects the operation if the file changed after it was read. New files can be created with write_file, or with edit by passing an empty old_string.

When Plan auto mode is enabled with /plan, the CLI also exposes two planning tools to the selected model:

set_plan       Set the visible ordered plan for a multi-step task
update_plan    Update one visible plan step as work progresses

These planning tools only update the local terminal UI; they do not read files, write files, or run commands.

MCP Tools

Interactive chat and one-shot prompts can use two kinds of MCP tools:

• Server-side MCP tools configured in the Setsuna Agent backend. The CLI renders their mcp_tool_start, mcp_tool_done, and mcp_tool_error stream events, and asks for confirmation when the backend sends an MCP approval question.
• Local MCP tools configured on this machine. The CLI reads JSON config, discovers MCP tools with tools/list, exposes them as function tools, and executes them with tools/call.

Local MCP config is loaded from:

~/.setsuna/cli/mcp.json
<workspace>/.mcp.json
<workspace>/.setsuna/mcp.json

Workspace config overrides global config when a server key is reused.

Example local npx MCP server:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "requireApproval": "always"
    }
  }
}

Example Streamable HTTP MCP server:

{
  "mcpServers": {
    "search": {
      "transport": "streamableHttp",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      },
      "requireApproval": "always"
    }
  }
}

Server-side MCP servers are configured from the web admin MCP page. They can use either Streamable HTTP endpoints or stdio commands such as:

{
  "mcpServers": {
    "MiniMax": {
      "command": "uvx",
      "args": ["minimax-coding-plan-mcp"],
      "env": {
        "MINIMAX_API_KEY": "<token>",
        "MINIMAX_MCP_BASE_PATH": "/data/minimax"
      }
    }
  }
}

After syncing tools and enabling the MCP server on the Agent config page, the web Agent and Setsuna CLI can both use those tools through the backend.

Useful chat commands:

/mcp          Show local MCP status and config paths
/mcp list     Show discovered local MCP tools
/mcp reload   Reload local MCP config and restart local MCP clients
/mcp on       Enable local MCP tools
/mcp off      Disable local MCP tools

/mcp reports only local MCP tools loaded by the CLI. Server-side MCP tools configured in the Setsuna Agent backend are injected by the backend during /agent/stream; the CLI renders those calls when they happen, but they are not included in the local MCP tool count.

Local MCP calls require confirmation by default. Set "requireApproval": "never" on a trusted server only if you want calls from that server to run without the extra prompt.

In non-interactive setsuna -p "question" mode, the CLI cannot ask for Y/N confirmation. Local MCP tools with "requireApproval": "always" are denied automatically; trusted local MCP tools must set "requireApproval": "never" to run from scripts. Backend MCP approval questions are also denied automatically in -p mode.

When multiple providers expose the same model code, Setsuna CLI keeps them as separate choices and stores the selection as provider:model, for example rehdasu:gpt-5.5.

The interactive chat requires a real TTY. Use pnpm start -- -p "question" for scripts, pipes, or CI.

Backend Contract

Phase 1 calls the existing proxy endpoints:

GET  /api/openai/v1/models
POST /api/openai/v1/chat/completions

Authentication is sent as:

Authorization: Bearer <api-key>

Future phases can add web authorization, MCP, richer text editing, file references, tool result panes, and session resume without changing the saved config shape.