development
claude/smbcloud-github-app-k9641p
development
feature/apps
feature/build-release
feature/ci-docs
feature/ci-ruby-gems
feature/cicd
feature/completion
feature/dist-nuget
feature/fix-ci-sdk-pypi-rubygem
feature/fix-clippy-on-stable-channel
feature/fix-deployment-script
feature/github-email
feature/gresiq-v1
feature/project-new-structure
feature/rsync-deploy
feature/ruby-runner
feature/sdk-npm
feature/sdk-workflows
feature/smbcloud-cli-release-npm
feature/smbcloud-deploy
feature/wasm
main
release/v0.7.4
| 1 | # Interfaces: headless, TUI, and MCP |
| 2 | |
| 3 | `smb` presents through one of three interfaces, chosen at runtime. The default |
| 4 | is **headless** — plain, line-based text that works the same in a terminal, a |
| 5 | pipe, or a script. Two global flags switch interface: |
| 6 | |
| 7 | | Flag | Interface | What it does | |
| 8 | |---|---|---| |
| 9 | | _(none)_ | **Headless** (default) | Plain-text output. Interactive prompts still appear on a TTY unless `--ci` is set. No full-screen takeover. | |
| 10 | | `--tui` | **TUI** | Full-screen interactive views (`ratatui`) for the read commands. | |
| 11 | | `--mcp` | **MCP** | Runs as a Model Context Protocol server over stdio instead of a one-shot command. Implies non-interactive. | |
| 12 | |
| 13 | `--tui` and `--mcp` are mutually exclusive. The `--ci` flag is orthogonal: it |
| 14 | forces non-interactive behavior (see |
| 15 | [CI / non-interactive deploys](./ci.md)) and applies to the |
| 16 | headless interface; `--mcp` is always non-interactive regardless of `--ci`. |
| 17 | |
| 18 | ## Headless (default) |
| 19 | |
| 20 | The default interface prints plain text and never seizes the terminal, so it is |
| 21 | safe to pipe or redirect: |
| 22 | |
| 23 | ```sh |
| 24 | smb me # plain key/value account block |
| 25 | smb project list # plain table |
| 26 | smb project show --id <id> # plain detail block |
| 27 | smb project deployment # plain table (or detail with --id <id>) |
| 28 | ``` |
| 29 | |
| 30 | On a real terminal, commands that need input still prompt (project setup, a |
| 31 | monorepo target picker, delete confirmations). Add `--ci` — or run under CI — to |
| 32 | turn those prompts off and fail fast instead of blocking. |
| 33 | |
| 34 | ## TUI (`--tui`) |
| 35 | |
| 36 | `--tui` renders the read commands as full-screen interactive views. Press |
| 37 | `q` / `Esc` to leave a view and return to the shell. |
| 38 | |
| 39 | ```sh |
| 40 | smb --tui me |
| 41 | smb --tui project list |
| 42 | smb --tui project show --id <id> |
| 43 | smb --tui project deployment |
| 44 | ``` |
| 45 | |
| 46 | Destructive confirmations (e.g. `project delete`) show a full-screen danger |
| 47 | dialog under `--tui`; in the headless interface they ask inline instead. |
| 48 | |
| 49 | ## MCP (`--mcp`) |
| 50 | |
| 51 | `smb --mcp` starts an MCP (Model Context Protocol) server that speaks |
| 52 | JSON-RPC over stdio. Instead of running a single command and exiting, it stays |
| 53 | up and exposes smbCloud operations — 31 tools spanning accounts, projects, |
| 54 | tenants, Mail, and Auth — as MCP **tools** that an MCP-capable client |
| 55 | (Claude Desktop, Claude Code, Cursor, or any other assistant/agent) can call. |
| 56 | The subcommand is ignored in this mode. |
| 57 | |
| 58 | Mobile and TV app automation is a separate profile: use |
| 59 | `smb --mcp --scope automation` or the standalone `xcrs --mcp` server. Both |
| 60 | expose the same focused, cross-platform automation tool set without mixing |
| 61 | device controls into the smbCloud resource tools. |
| 62 | |
| 63 | Authentication uses the token stored by `smb login`, so log in once before |
| 64 | starting the server. Tools run non-interactively and return structured JSON — |
| 65 | including the `*_delete` tools, which apply immediately with no confirmation |
| 66 | prompt. |
| 67 | |
| 68 | For the client setup guide and the full tool reference, see |
| 69 | [MCP Server](./mcp.md). For running native Apple-platform runners, see |
| 70 | [ControlKit runners](./controlkit.md). |