---
title: Interactive TUI
description: Use bunx smithers-orchestrator init, up --interactive, and workflow run --interactive to pick workflows, collect inputs, and watch runs in the full-screen terminal monitor.
---

Smithers has two terminal UI surfaces:

1. `bunx smithers-orchestrator init` asks one interactive question (your preferred coding agent) unless you pass `--yes` / `--non-interactive`.
2. `bunx smithers-orchestrator up --interactive` and `bunx smithers-orchestrator workflow run --interactive` open the run launcher and then the full-screen monitor.

The old standalone `bunx smithers-orchestrator tui` command was removed in `0.20.2`. The current TUI path is the `--interactive` mode on run commands.

## Interactive setup

Run `init` in a human terminal. It shows which coding agents it detected, asks which one you prefer, installs the workflow pack with defaults plus that agent's plugin (or skill if no plugin exists), and then opens a hijacked tutorial session hosted by that agent:

```bash
bunx smithers-orchestrator init
```

Pass `--agent claude` (or `codex`, `pi`, ...) to skip the question, and `--no-tutorial` to skip the guided session. For CI, scripts, or agent-driven setup, use the non-interactive form:

```bash
bunx smithers-orchestrator init --yes
```

## Interactive run launcher

Use `up --interactive` when you want Smithers to help pick a workflow and collect inputs:

```bash
bunx smithers-orchestrator up --interactive
```

From an interactive TTY, omitting the workflow argument also opens the same launcher:

```bash
bunx smithers-orchestrator up
```

<Frame caption="Captured from tmux: up --interactive opens a searchable workflow picker before it starts a run.">
  <img src="/images/tui/up-interactive-picker.svg" alt="Terminal screenshot of bunx smithers-orchestrator up --interactive showing the workflow picker" />
</Frame>

Use `workflow run --interactive` when you prefer workflow IDs over file paths:

```bash
bunx smithers-orchestrator workflow run --interactive
bunx smithers-orchestrator workflow run WORKFLOW_ID --interactive
```

Passing a workflow ID skips the picker and goes straight to the input prompts for that workflow:

<Frame caption="Captured from tmux: workflow run hello --interactive preselects hello and prompts for its input schema.">
  <img src="/images/tui/workflow-run-interactive-input.svg" alt="Terminal screenshot of workflow run hello --interactive prompting for the name input" />
</Frame>

## Full-screen monitor

After the launcher starts the run, Smithers detaches the workflow process and hands your terminal to the full-screen monitor from `@smithers-orchestrator/tui`. The monitor connects to the workspace Gateway, starts one if needed, and streams the run tree, output, logs, diffs, timeline, and hijack state.

```bash
bunx smithers-orchestrator workflow run hello --interactive
```

<Frame caption="Captured from tmux: after a real hello run finishes, the monitor still shows the run tree and selected node details.">
  <img src="/images/tui/interactive-monitor-hello.svg" alt="Terminal screenshot of the full-screen Smithers TUI monitor showing a finished hello run" />
</Frame>

Useful keys:

| Key | Action |
| --- | --- |
| `1` to `4` | Switch primary tabs |
| `g` | Graph mode |
| `l` | Logs mode |
| `t` | Timeline mode |
| `h` | Hijack mode |
| `?` | Help |
| `q` | Quit the monitor |

There is no silent fallback. If the TUI package cannot be resolved, the command fails with `TUI_MONITOR_UNAVAILABLE` while the detached run keeps running. Watch it with `bunx smithers-orchestrator ps`, `bunx smithers-orchestrator inspect RUN_ID`, or the run log file.

## Command map

| Need | Command |
| --- | --- |
| Interactive setup + tutorial | `bunx smithers-orchestrator init` |
| Non-interactive setup | `bunx smithers-orchestrator init --yes` |
| Pick a workflow and run it | `bunx smithers-orchestrator up --interactive` |
| Pick a workflow ID and run it | `bunx smithers-orchestrator workflow run --interactive` |
| Run a known workflow ID interactively | `bunx smithers-orchestrator workflow run WORKFLOW_ID --interactive` |
| Run a known workflow file interactively | `bunx smithers-orchestrator up .smithers/workflows/hello.tsx --interactive` |
| Run the upgrade workflow with the monitor | `bunx smithers-orchestrator upgrade --interactive` |
| Scripted or CI run | `bunx smithers-orchestrator up WORKFLOW -d` |

Agents should suggest the interactive commands to humans, but should not run them through an automation harness. If an agent is executing a workflow itself, use `-d`, `--format json`, `ps`, `logs`, `inspect`, and `events` instead.
