# Core CLI TUI

99Pages Agentic OS Powered By Ng Tick Kee (Founder of UiBC Training Hub)

V3 includes a lightweight Core CLI TUI inspired by simple slash-command agent
CLIs and terminal line editors: calm prompt, grouped commands, a persistent
bottom guide, explicit command lifecycle, and no hidden business logic.

The TUI is intentionally thin but production-facing:

- It does not own business logic.
- It maps slash commands to the same `99p` command handlers.
- It uses the same run event stream, MCP registry, approval gate, and SubCLI connector.
- It treats SubCLI and Keybox as first-class operator surfaces, not hidden MCP details.
- It prints the command being executed and a clear done/error state.
- It stays useful without any HTML5 frontend.

## Start

```powershell
99p tui
```

## Commands

```text
/help
/run <task>
/runs
/events <run_id>
/watch <run_id>
/worker once <run_id>
/shell
/approve <approval_id> [--resume]
/mcp list
/mcp manifest
/mcp audit
/mcp status [module]
/mcp start <module>
/mcp stop <module>
/mcp open <module>
/mcp tools <module>
/mcp call <module> <tool> [json]
/mcp resume <approval_id>
/apps list
/apps manifest
/apps status [app]
/apps open <app>
/apps tools <app>
/apps call <app> <tool> [json]
/subcli profiles
/subcli spawn <profile> <task>
/subcli result <job_id> [wait_sec]
/subcli mcp <list|status|open|tools|call> ...
/keybox tools
/keybox call <tool> [json]
/project tools|call|open|status ...
/workflow tools|call|open|status ...
/miniapp tools|call|open|status ...
/fs walk|actions <tools|call> ...
/pty tools|call|open|status ...
/browser tools|call|open|status ...
/device tools|call|open|status ...
/wiki tools|call|open|status ...
/library tools|call|open|status ...
/trace tools|call|open|status ...
/harness tools|call|open|status ...
/ssh tools|call|open|status ...
/telegram start
/telegram status
/telegram stop
/models
/sentinel once
/exit
```

Plain text without `/` becomes `/run <text>`.

## Windows Shell Policy

All Windows CLI surfaces must open through PowerShell with UTF-8 input/output.
This keeps Chinese input stable across Core CLI, TUI, SubCLI, PTY, and MCP app
calls.

```powershell
99p shell
```

`99p shell` opens a PowerShell UTF-8 session. MCP processes receive:

```text
AGENTIC_OS_CLI_SHELL=powershell
AGENTIC_OS_CLI_ENCODING=utf-8
AGENTIC_OS_WINDOWS_SHELL=powershell
```

Modules that need a shell should honor those variables and avoid falling back to
`cmd.exe`.

## Footer Guide

The TUI prints a line-editor style guide so operators do not have to memorize
the first layer of commands:

```text
^G Help  ^X Exit  ^R Run  ^L Runs  ^A Approve  ^M MCP  ^S SubCLI  ^K Keybox  ^F FS
```

These labels are guidance for the terminal surface and documentation. Slash
commands remain the stable automation contract for humans, agents, Telegram,
and app.99pages.uk.

## MCP Slash Shortcuts

These commands are thin routing shortcuts first. They do not introduce custom
panels yet; they keep high-frequency MCPs reachable while the richer TUI is
designed module by module.

```powershell
99p project tools
99p workflow tools
99p miniapp tools
99p pty call <tool> '{"command":"dir"}'
99p browser call <tool> '{"url":"https://example.com"}'
99p device status
99p ssh tools
```

Filesystem is split on purpose:

```powershell
99p fs walk tools
99p fs walk call <tool> '{"path":"."}'
99p fs actions tools
99p fs actions call <tool> '{"path":"example.txt"}'
```

`fs-walk` is read-oriented. `fs-actions` is mutating and goes through approval
when the action is risky.

## Mini App Builder

Mini App Builder is also an MCP CLI surface first:

```powershell
99p miniapp tools
99p miniapp call <tool> '{"app":"crm-lite","source":"./data"}'
99p miniapp status
```

The first deliverables are data contracts and durable updates:

- Generate or revise the app schema.
- Prepare the local database or migration plan.
- Write/import the user's data.
- Emit a final report and update events.

Visual screens are optional later work. app.99pages.uk or a user-supplied UI can
project the database when a customer actually needs that view.

## Why Slash Commands

Slash commands keep the Core CLI predictable for humans and agents:

- Easy for users to learn.
- Easy for agents to drive.
- Easy to mirror into Telegram and Cockpit.
- No token spending for local command parsing.

## Commercial Scope

The TUI is the local operating surface for commercial delivery. app.99pages.uk
is the remote HTML5/PWA projection. MCP-specific HTML5 frontends are optional and
not part of the default maintenance burden.

## MCP Calls

Generic MCP calls use JSON arguments:

```powershell
99p mcp call subcli SubCLIStats
99p mcp call subcli SubCLIResult '{"job_id":"sj:abc","wait_sec":2}'
```

High-risk MCP calls create an approval event instead of executing directly. The
operator can resume them explicitly:

```powershell
99p mcp call pty Shell '{"command":"dir"}'
99p approve <approval_id> --resume
```

Not every MCP has UI. `mcp open <module>` only opens modules that advertise an
`open_url`; capability-only modules should be operated through `tools` and
`call`.

## SubCLI

SubCLI is independent from Core CLI, but it runs under the Core login/session.
It is the manual and agent-guided operator for MCP capabilities. Profiles map
to safe module allowlists:

```powershell
99p subcli profiles
99p subcli spawn project_triage "check this project and summarize risks"
99p subcli result sj:abc 5
```

If the result reports `chat: backend not configured`, SubCLI is wired but AI Workforce credentials are not available in that environment.

## Keybox And Secret Writes

Some CLI work writes secrets, provider keys, or local tokens. Those operations
must be visible in the TUI and must pass the approval gate.

```powershell
99p keybox tools
99p keybox call <tool> '{"name":"OPENAI_API_KEY","value":"..."}'
```

The exact tool name comes from `99p keybox tools` because Keybox is an MCP
module. Write/export actions are guarded through the same flow as high-risk MCP
calls:

```powershell
99p keybox call <tool> '{"name":"EXAMPLE","value":"secret"}'
99p approve <approval_id> --resume
```

## Telegram Background Poller

The Telegram transport can run as a controlled local background process:

```powershell
99p telegram start
99p telegram status
99p telegram stop
```

`start` launches `agentic-mcp-telegram-bot` in `AUTOPOLL_ONLY` mode. It enables
long polling, smart reply, and SubCLI agent loop using the local host
`.agentic-os` registry, license, and Telegram token file. It writes:

- PID: `%USERPROFILE%\.agentic-os\run\telegram-autopoll.pid`
- Log: `%USERPROFILE%\.agentic-os\logs\telegram-autopoll.log`

This is intentionally not an OS boot service yet. Cockpit can call the same
commands later for a Start/Stop switch.
