Command Support Inventory
This page inventories the command surfaces discovered during the 2026-06-10 command review, with an EPIC-008 command-center addendum smoke-tested on 2026-06-17, Workspace catalog registration verified on 2026-08-10, and the ostwin import pack importer added on 2026-08-23. It complements the CLI Commands reference by showing where each command is implemented, how it was smoke-tested, and which commands require a live dashboard or external services.
Review scope
Section titled “Review scope”| Surface | Source of truth | Notes |
|---|---|---|
ostwin CLI |
.agents/bin/ostwin and .agents/bin/ostwin.ps1 |
Unified PowerShell entrypoint. The Unix executable uses a pwsh shebang; Windows uses ostwin.cmd to invoke ostwin.ps1. |
| MCP extension manager | .agents/mcp/mcp-extension.sh |
Reached through ostwin mcp ... except ostwin mcp sync, which calls resolve_opencode.py directly. |
| Channel CLI | .agents/bin/channel_cmd.py |
Reached through ostwin channel ...; all operational subcommands call the dashboard REST API. |
| Search engine manager | .agents/search-engine.sh |
Manages a user-owned SearXNG runtime under OSTWIN_HOME/search-engine. |
| Role subcommands | .agents/roles/*/subcommands.json |
Currently manager and macos-automation-engineer expose role subcommands. |
| Bot slash commands | bot/src/commands.ts |
Registry used by Discord, Telegram, and Slack connectors. |
ostwin MCP tools |
.agents/mcp/ostwin-server.py |
Tools exposed to OpenCode as deterministic MCP calls that proxy dashboard REST APIs. |
Safe smoke-test matrix
Section titled “Safe smoke-test matrix”These commands were exercised in a non-destructive shell with a temporary OSTWIN_HOME and unused dashboard port where possible.
| Command | Result | Classification | Notes |
|---|---|---|---|
ostwin --help |
Pass | Safe | Main help renders all top-level commands. |
ostwin version |
Pass | Safe | Prints ostwin v<version> from .agents/config.json. |
ostwin plan help |
Pass | Safe | Shows create, start, list, clear. |
ostwin workspace --help |
Pass | Safe | Documents authenticated Workspace catalog registration. |
ostwin workspace create ... --json |
Pass | Isolated mutation | Verified against a temporary local HTTP fixture; request path, payload, credential header, result, conflict handling, and input validation are covered. |
ostwin skills help |
Pass | Safe | Shows sync, install, search, update, remove, list. |
ostwin import --help |
Pass (dispatch) | Safe | Launcher dispatch and the missing-module guard verified on 2026-08-23; argparse help is exercised by the Python test suite. No dashboard and no filesystem writes. |
ostwin import <folder> --dry-run |
Covered by tests | Safe | Plan-only. Reads the pack, resolves namespaces, and prints the ignored inventory without writing anything. |
ostwin import <folder> --yes |
Covered by tests | Isolated mutation | Exercised against a temporary local HTTP fixture and a temporary OSTWIN_STATE_DIR: namespace create/reuse, two directories sharing one namespace, skill and role writes, conflict skips, and --force replacement. Not run against a live dashboard in the smoke pass. |
ostwin mcp help |
Pass | Safe | Shows extension, credentials, test, compile, migrate, and init-project commands. |
ostwin search-engine --help |
Pass | Safe | Shows install/configure/start/stop/status/settings. |
ostwin channel --help |
Pass | Safe | Argparse help shows list/connect/disconnect/test/pair. |
ostwin memory help |
Pass | Safe | Shows namespace list/stats/tree/clear/delete/archive/export. |
ostwin dashboard help |
Pass | Safe | Shows server lifecycle and autostart commands. |
ostwin test --help |
Pass | Safe | Lists available Pester suites and flags. |
ostwin role |
Pass | Safe | Lists roles that have subcommands.json. |
ostwin role macos-automation-engineer |
Pass | Safe | Lists the nine macOS script shortcuts. |
ostwin mac app help |
Pass | Safe | Confirms app lifecycle usage. |
ostwin mac window help |
Pass | Safe | Confirms Accessibility-gated window commands. |
ostwin mac capture help |
Pass | Safe | Confirms Screen Recording-gated capture commands. |
ostwin config --help |
Pass | Safe | Shows get/set syntax. |
ostwin status --json |
Pass | Safe/read-only | Reads local .war-rooms state. |
ostwin rooms --json |
Pass | Safe/read-only | Reads command-center run state without human stdout pollution. |
ostwin room room-001 messages --full |
Pass | Safe/read-only | Full channel body access through room inspection. |
ostwin events --json --last 20 |
Pass | Safe/read-only | Reads structured event stream as JSON array. |
ostwin search <query> --json |
Pass | Safe/read-only | Searches bounded runtime evidence in temp fixtures. |
ostwin control pause --reason ... --non-interactive without --yes |
Pass | Negative safety | Fails closed and explains confirmation requirements. |
ostwin logs --last 1 |
Pass | Safe/read-only | Reads latest local channel message. |
ostwin dashboard status |
Pass | Safe/read-only | Reports whether a dashboard process listens on the configured port. |
ostwin search-engine status |
Pass | Safe/read-only | Reports runtime state and managed paths without starting SearXNG. |
ostwin mcp catalog |
Pass | Safe/read-only | Catalog command returns successfully even when no packages are present. |
ostwin mcp list |
Pass | Safe/read-only | Lists built-in MCP servers and installed extensions. |
ostwin mcp definitely-not-a-command |
Fixed | Negative test | Unknown MCP subcommands now exit non-zero instead of reporting failure with exit 0. |
Dashboard-dependent commands
Section titled “Dashboard-dependent commands”These commands are valid but need the dashboard API to be running and reachable at DASHBOARD_URL/DASHBOARD_PORT.
| Command family | Requires dashboard? | Why |
|---|---|---|
ostwin plan create, ostwin plan list |
Yes | Uses /api/plans/create, /api/plans, and related plan editor endpoints. |
ostwin workspace create |
Yes | Uses authenticated POST /api/workspaces; a successful registration is automatically included in the User Management Workspace catalog. |
ostwin channel list/connect/disconnect/test/pair |
Yes | Uses /api/channels/.... |
ostwin skills list |
Yes | Uses /api/skills. |
ostwin import (knowledge leg only) |
Yes | Uses /api/knowledge/namespaces... and /api/skills/sync; requires OSTWIN_API_KEY. Fails closed with DASHBOARD_UNREACHABLE rather than writing knowledge directly. --only skills and --only roles work with the dashboard down. |
ostwin memory list/stats/tree/clear/delete/archive/export |
Yes | Uses /api/amem/.... |
ostwin health |
Partially | Checks local components plus dashboard endpoints when available. |
Top-level CLI commands
Section titled “Top-level CLI commands”| Command | Supported subcommands/options | Implementation | Status |
|---|---|---|---|
run |
--dry-run, --resume, --sync, --expand, --plan-review, --enable-planning, --working-dir, --workspace-isolation, --non-interactive, --debug, --plain, --json-events |
.agents/bin/ostwin + .agents/plan/Start-Plan.ps1 + .agents/lib/Console.psm1 |
Supported; EPIC-008 smoke covers dry-run plain, debug, JSON-events, no-color/CI fallback. |
plan |
create, start, list, clear |
CLI + dashboard API + Start-Plan.ps1 |
Supported; help smoke-tested. |
workspace |
create --name NAME --slug SLUG [--description TEXT] [--json] |
CLI + authenticated POST /api/workspaces |
Supported; isolated CLI/API contract tests cover success, duplicate slug, validation, and credential requirements. |
init |
[directory], --yes, --help |
.agents/init.ps1 |
Supported. |
sync |
[directory] |
.agents/sync.ps1 |
Supported for directories already initialized with .agents/; exits non-zero for uninitialized targets. |
status |
--json, --watch |
.agents/war-rooms/Get-WarRoomStatus.ps1 |
Supported; --json smoke-tested. |
logs |
[room-id], --follow, --type, --from, --last |
.agents/logs.ps1 |
Supported; read-only smoke-tested. |
stop |
--force |
Inline CLI process shutdown | Supported; destructive, not smoke-tested. |
rooms |
--json |
.agents/bin/run-state.ps1 + .agents/lib/RunState.psm1 |
Supported; read-only command-center smoke-tested. |
room |
<room-id> [brief|tasks|qa|messages|logs|artifacts|status], --json, --full, --last, --follow where supported |
.agents/bin/run-state.ps1 + .agents/lib/RunState.psm1 + .agents/lib/AgentMessageRenderer.psm1 |
Supported; read-only command-center smoke-tested. |
epic |
<EPIC-ID> [brief|tasks|qa|messages|logs|artifacts|status] |
.agents/bin/run-state.ps1 + .agents/lib/RunState.psm1 |
Supported; resolves epic refs to rooms. |
events / timeline |
--json, --last N, --follow |
.agents/bin/run-state.ps1 + .agents/lib/EventStream.psm1 |
Supported; event JSON and human timeline smoke-tested. |
inspect |
no subcommands | .agents/bin/run-state.ps1 |
Supported; prints read-only inspection help. |
search |
<query>, --limit N, --json |
.agents/bin/run-state.ps1 + .agents/lib/RunState.psm1 |
Supported; bounded runtime evidence search smoke-tested. |
control |
pause, resume, stop, rerun, kill, force-transition |
.agents/bin/control.ps1 + .agents/lib/Control.psm1 + .agents/lib/EventStream.psm1 |
Supported with confirmation/audit safeguards; smoke uses only temp fixtures/stale PID. |
dashboard |
start, stop, restart, status, logs, autostart, --port, --project-dir |
.agents/dashboard.sh / .agents/dashboard.ps1 |
Supported; status and help smoke-tested. |
channel |
list, connect, disconnect, test, pair |
.agents/bin/channel_cmd.py |
Supported; help smoke-tested. |
config |
--get, --set, --help |
.agents/config.ps1 |
Supported; help smoke-tested. |
role |
list roles, list role subcommands, dispatch role subcommand | Role subcommands.json manifests |
Supported; list paths smoke-tested. |
mac |
app, window, click, type, capture, system, finder, axbridge, devtools |
Shortcut to role macos-automation-engineer |
Supported; help smoke-tested for representative scripts. |
health |
--json |
.agents/health.ps1 |
Supported; may report unhealthy without dashboard. |
skills |
sync, install, search, update, remove, list |
.agents/sync-skills.ps1, .agents/clawhub-install.ps1 |
Supported; help smoke-tested. |
import |
<folder>, --only, --namespace DIR=NS, --knowledge-language, --no-vision-ocr, --no-extract-entities, --poll-timeout, --no-wait, --role-model, --role-timeout, --verify-model, --force, --yes, --dry-run, --json, --dashboard-url |
.agents/bin/ostwin -> dashboard.lib.pack_import.cli |
Supported; launcher dispatch verified 2026-08-23, plan/apply behaviour covered by isolated fixtures. Prompts on a TTY, so the launcher passes stdin through unredirected. |
mcp |
install, list, catalog, remove, sync, test, compile, credentials, migrate, init-project |
.agents/mcp/mcp-extension.sh, resolve_opencode.py |
Supported; help/list/catalog smoke-tested. |
search-engine |
install, configure, start, stop, status, settings |
.agents/search-engine.sh |
Supported; status/help/settings smoke-tested. settings is safe before configure and prints guidance. |
reload-env |
no subcommands | Inline CLI MCP config updater | Supported; writes MCP configs. |
memory |
list, stats, tree, clear, delete, archive, export |
Inline dashboard API wrapper | Supported; help smoke-tested. |
test |
--suite, --path, --verbose |
Inline Pester runner | Supported; help smoke-tested. |
version |
-v, --version |
Inline version printer | Supported; smoke-tested. |
Bot slash command registry
Section titled “Bot slash command registry”Bot commands are configured once in COMMAND_REGISTRY and then exposed by each connector. Discord includes the voice-only commands; Telegram and Slack omit commands marked discordOnly.
| Category | Commands |
|---|---|
| Plans and AI | menu, help, draft <idea>, edit, viewplan, startplan, resume, assets, setdir <path>, cancel, clear, feedback <text> |
| Monitoring | dashboard, status, errors, logs <room_id>, health, progress, plans |
| Skills and roles | skills, skillsearch <query>, skillinstall <slug>, skillremove <name>, skillsync, roles |
| System | triage <room_id>, clearplans, new, restart, launchdashboard, preferences, subscriptions |
| Discord voice only | join, leave, ping |
ostwin MCP server tools
Section titled “ostwin MCP server tools”The ostwin MCP server exposes dashboard actions as typed tools for OpenCode. These tools are dashboard-dependent and return JSON strings.
| Tool | Purpose |
|---|---|
list_plans |
List every plan with ID, title, and status. |
get_plan_status(plan_id) |
Return one plan plus its epic statuses. |
create_plan(idea, working_dir?) |
Create and AI-draft a new plan, then save it. |
refine_plan(plan_id, instruction) |
Ask the dashboard to refine and save an existing plan. |
launch_plan(plan_id) |
Launch a saved plan into war-rooms. |
resume_plan(plan_id) |
Mark a plan as running again. |
get_war_room_status |
Return aggregate dashboard stats. |
get_logs(plan_id, room_id, limit?) |
Read recent war-room channel messages. |
get_health |
Check dashboard health. |
search_skills(query) |
Search ClawHub through the dashboard API. |
get_plan_assets(plan_id) |
List plan-attached assets. |
get_memories(plan_id) |
Stub currently returning an empty memories array. |
Removal guidance
Section titled “Removal guidance”The broken clone-role shortcut was removed from public help/docs because it delegated to a missing manager clone role subcommand. The invalid ostwin mac click 100 200 example was replaced with ostwin mac click help; real click actions must include a click subcommand such as ostwin mac click click 100 200 and require Accessibility permission. The unknown MCP subcommand path was fixed to return exit 1, and command wrappers now propagate child-process failures for sync and role/mac dispatch. Commands that require credentials, dashboard availability, Git worktrees, Accessibility permission, Screen Recording permission, or destructive state changes remain documented but should be tested in an environment prepared for those side effects.