# CLI Quick Recipes

Practical command patterns for `fmtk`, the short alias for the canonical
`flutter-mcp-toolkit` CLI.

If you have not decided between interfaces yet, read [CLI vs MCP](/start_here/cli_vs_mcp) first.

## Prerequisites

From repo root:

```bash
make install
```

That builds local binaries under `mcp_server_dart/build/`. Add that directory
to `PATH`, or call the local binary directly:

```bash
export PATH="$PWD/mcp_server_dart/build:$PATH"
fmtk --help
# or: ./mcp_server_dart/build/fmtk --help
```

## 0. Two-Step Agent Flow (Recommended)

Step 1: run app in debug mode.

```bash
cd /ABSOLUTE/PATH/TO/FLUTTER_APP
flutter run --debug --host-vmservice-port=8182 --dds-port=8181
```

Step 2: run a single runtime validation command.

```bash
fmtk --save-images validate-runtime \
  --target ws://127.0.0.1:8181/<token>/ws \
  --timeout-ms 10000 \
  --after-reload
```

This single command runs doctor preflight, toolkit-extension gating, screenshot capture, layout details, app errors, and optional reload verification.

Optional: add `--install-skill` to install bundled skill `flutter-mcp-cli-runtime-validation` into `$CODEX_HOME/skills` during step 2. For the full skill set across agents, prefer `flutter-mcp-toolkit init codex` or `npx skills add Arenukvern/mcp_flutter -a codex -y` ([overview](/ai_agents/overview)).

## 1. Inspect Available Capabilities

```bash
fmtk capabilities
fmtk schema
fmtk schema --name get_app_errors
```

## 2. Run One-Shot Health Checks

```bash
fmtk doctor --json
fmtk exec --name status --args '{}'
fmtk exec --name get_vm --args '{}'
fmtk batch --steps '[{"name":"status","args":{}},{"name":"get_app_errors","args":{"count":5}}]'
```

## 3. CLI-First Runtime Preflight (Required Before App Inspection)

```bash
fmtk exec --name get_extension_rpcs --args '{}'
```

Confirm these extensions exist before claiming screenshot/layout/error inspection works:

- `ext.mcp.toolkit.app_errors`
- `ext.mcp.toolkit.view_details`
- `ext.mcp.toolkit.view_screenshots`
- `ext.mcp.toolkit.inspect_widget_at_point`

If any are missing:

- Add `mcp_toolkit` to app dependencies.
- Ensure startup initializes toolkit before `runApp`:
  `MCPToolkitBinding.instance..initialize()..initializeFlutterToolkit();`
- Run full restart (`hot_restart_flutter` or rerun app), then retry `get_extension_rpcs`.

## 4. Pull Common Debug Data

```bash
fmtk exec --name get_app_errors --args '{"count":5}'
fmtk exec --name get_view_details --args '{}'
fmtk exec --name get_screenshots --args '{}'
fmtk exec --name discover_debug_apps --args '{}'
fmtk exec --name capture_ui_snapshot --args '{"includeViewDetails":true,"includeErrors":true}'
fmtk exec --name inspect_widget_at_point --args '{"x":120,"y":220}'
```

## 5. Verify Runtime Changes (Agent-Style)

```bash
# baseline visual/layout state
fmtk exec --name get_screenshots --args '{}'
fmtk exec --name get_view_details --args '{}'

# after code edits
fmtk exec --name hot_reload_flutter --args '{}'
fmtk exec --name get_screenshots --args '{}'
fmtk exec --name get_view_details --args '{}'
```

## 6. Handle Multiple Debug Targets Explicitly

When calls fail with `connection_selection_required`, retry with a target URI:

```bash
fmtk exec \
  --name get_vm \
  --args '{"connection":{"targetId":"ws://127.0.0.1:59490/<token>/ws"}}'
```

## 7. Safest Explicit Targeting (Recommended)

If you have Flutter machine output with `app.debugPort.wsUri`, prefer `connection.uri` and paste that value exactly:

```bash
fmtk exec \
  --name get_vm \
  --args '{"connection":{"uri":"ws://127.0.0.1:59490/<token>/ws"}}'
```

## 8. Use Session Lifecycle Commands

```bash
fmtk exec --name session_start --args '{"mode":"uri","uri":"ws://127.0.0.1:8181/<token>/ws"}'
fmtk exec --name session_exec --args '{"command":"get_app_errors","arguments":{"count":3}}'
fmtk exec --name session_end --args '{}'
```

## 9. Create Reproducible Artifacts

```bash
fmtk snapshot create --name baseline --args '{"commands":[{"name":"status","args":{}},{"name":"get_app_errors","args":{"count":5}}]}' --check --diff
fmtk snapshot create --name baseline --args '{"commands":[{"name":"status","args":{}},{"name":"get_app_errors","args":{"count":5}}]}' --backup
fmtk snapshot create --name after_fix --args '{"commands":[{"name":"status","args":{}},{"name":"get_app_errors","args":{"count":5}}]}' --no-overwrite
fmtk snapshot diff --from baseline --to after_fix
fmtk bundle create --from-snapshot after_fix --check --diff
fmtk bundle create --from-snapshot after_fix --backup
```

## 10. CI Script Template

```bash
#!/usr/bin/env bash
set -euo pipefail

make install
export PATH="$PWD/mcp_server_dart/build:$PATH"

fmtk doctor --json
fmtk exec --name get_extension_rpcs --args '{}'
fmtk exec --name status --args '{}'
fmtk exec --name get_app_errors --args '{"count":10}'
fmtk snapshot create --name ci_run --args '{"commands":[{"name":"status","args":{}},{"name":"get_app_errors","args":{"count":10}}]}' --check --diff
```

## 11. Common Failure Recovery

- `connection_selection_required`: retry with `connection.targetId`.
- `target_not_found` with `connection.targetId`: retry with `connection.uri` using exact `app.debugPort.wsUri`.
- `mcp_toolkit` extensions missing: app cannot be inspected via screenshot/layout/errors until toolkit is installed, initialized, and app is restarted.
- Screenshots are blank or stale: ensure app window is visible/foreground (not minimized/headless), then retry `get_screenshots`.
- App was just instrumented but extensions still missing: hot reload may be insufficient; run `hot_restart_flutter` or rerun app.
- First explicit-URI connect times out (`connect_failed` with 2s timeout): retry the same command once, then run `doctor --json --target <ws_uri> --timeout-ms 10000` to confirm reachability.
- No data from app tools: ensure Flutter app is running in debug mode and VM service is enabled.
- Schema validation failures: use nested `connection` object, not flat `host`/`port` aliases.

## Related Docs

- [MCP configuration](/core/mcp_configuration)
- [Interaction cookbook](/guides/interaction_cookbook)
- [Dynamic tool registry](/core/dynamic_tools_registry)
- [AI troubleshooting](/ai_agents/troubleshooting)