Skip to content

docs(cli): align interactivity and --human-friendly guidance with actual behavior #705

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
miguel-heygen merged 2 commits into from
May 10, 2026
+14 −12
Merged

docs(cli): align interactivity and --human-friendly guidance with actual behavior #705

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f083888
docs(cli): clarify interactivity defaults and human-friendly scope
May 10, 2026
e0573c1
docs(cli): remove remaining invalid init --human-friendly references
May 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 14 additions & 12 deletions docs/packages/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,14 +35,15 @@ npx hyperframes <command>

## Agent-Friendly by Default

The CLI is **non-interactive by default** — designed so AI agents (Claude Code, Gemini CLI, Codex, Cursor) can drive every command without prompts or interactive UI.
The CLI is **agent-friendly by default**: commands support explicit flags and parseable output so automation can run reliably.

- All inputs are passed via flags (e.g., `--example`, `--video`, `--output`)
- Inputs can be passed via flags (for example, `--example`, `--video`, `--output`)
- Missing required flags fail fast with a clear error and usage example
- Output is plain text suitable for parsing
- No interactive prompts, spinners, or selection menus

Add `--human-friendly` to any command to enable the interactive terminal UI with prompts, spinners, and selection menus.
Interactivity is command-specific. For example, `init` uses prompts on TTY by default; pass `--non-interactive` to force non-interactive mode.

`--human-friendly` is also command-specific (for example, `catalog`). It is not a global flag on every command.

<Tabs>
<Tab title="Agent mode (default)">
Expand All @@ -55,9 +56,11 @@ Add `--human-friendly` to any command to enable the interactive terminal UI with
</Tab>
<Tab title="Human mode">
```bash
# Interactive prompts, spinners, and selection menus
npx hyperframes init --human-friendly
npx hyperframes upgrade
# Command-specific interactive flow
npx hyperframes init my-video

# Interactive picker supported by catalog
npx hyperframes catalog --human-friendly
```
</Tab>
</Tabs>
Expand Down Expand Up @@ -155,13 +158,13 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
# Include Tailwind CSS browser-runtime support
npx hyperframes init my-video --example blank --tailwind

# Human mode — interactive prompts
npx hyperframes init --human-friendly
# Human mode — interactive prompts on TTY by default
npx hyperframes init my-video
```

| Flag | Description |
|------|-------------|
| `--example, -e` | Example to scaffold (required in default mode, interactive in `--human-friendly`) |
| `--example, -e` | Example to scaffold (required in non-interactive mode, prompted on TTY by default) |
| `--resolution` | Canvas preset: `landscape` (1920×1080), `portrait` (1080×1920), `landscape-4k` (3840×2160), `portrait-4k` (2160×3840). Aliases: `1080p`, `4k`, `uhd`. Default: keep template dimensions. |
| `--video, -V` | Path to a video file (MP4, WebM, MOV) |
| `--audio, -a` | Path to an audio file (MP3, WAV, M4A) |
Expand All @@ -170,7 +173,6 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
| `--skip-transcribe` | Skip automatic whisper transcription |
| `--model` | Whisper model for transcription (e.g. `small.en`, `medium.en`, `large-v3`) |
| `--language` | Language code for transcription (e.g. `en`, `es`, `ja`). Filters non-target speech. |
| `--human-friendly` | Enable interactive terminal UI with prompts |

| Example | Description |
|----------|-------------|
Expand All @@ -180,7 +182,7 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
| `swiss-grid` | Structured grid layout |
| `vignelli` | Bold typography with red accents |

In default (agent) mode, `--example` is required — the CLI errors with a usage example if missing. In `--human-friendly` mode, you choose interactively. When `--video` or `--audio` is provided, the CLI automatically transcribes the audio with Whisper and patches captions into the composition (use `--skip-transcribe` to disable).
In non-interactive mode, `--example` is required — the CLI errors with a usage example if missing. In interactive mode (default on TTY), you choose the example interactively. Pass `--non-interactive` to require `--example` via flag. When `--video` or `--audio` is provided, the CLI automatically transcribes the audio with Whisper and patches captions into the composition (use `--skip-transcribe` to disable).

`--tailwind` injects the pinned Tailwind v4 browser runtime into scaffolded HTML and exposes a `window.__tailwindReady` promise that renders wait on before capturing frame 0. Use the `/tailwind` skill when editing these projects so agents follow v4 CSS-first patterns instead of v3 `tailwind.config.js` and `@tailwind` directive patterns. The browser runtime is still intended for scaffolded projects and quick iteration; for fully offline or locked-down production renders, compile Tailwind to CSS and include the stylesheet directly.

Expand Down
Loading