Penguin CLI – Command Reference (v0.9.x)

Penguin now exposes multiple terminal entrypoints on top of the same runtime:

penguin — default launcher for the interactive TUI
ptui / penguin-tui — explicit aliases for the same TUI runtime
penguin-cli — headless/scriptable CLI for prompts, config, projects, and automation

This page documents the currently implemented command surface and calls out where older docs were too optimistic.

Getting help

# Default launcher help
penguin --help

# Headless CLI help
penguin-cli --help

# Help for a specific sub-command
penguin-cli project --help
penguin-cli project task --help
penguin-cli config --help

Quick start

1. Interactive chat (default TUI)

# Start an interactive chat session
penguin

# Equivalent explicit TUI aliases
ptui
penguin-tui

The Penguin TUI automatically emits OSC 7501 program status when stdout is a terminal. It reports the selected session as idle, working, waiting for approval/an answer/authentication, completed, or failed. Pressing a key acknowledges completion or failure; cancellation returns to idle. Messages are generic and do not include prompts, responses, or credentials. This is independent of notification settings, and terminals without support can ignore the reports. With tmux, enable passthrough (set -g allow-passthrough on). Headless CLI output and background-session records are not covered.

The tab title also shows [Idle], [Working], [Needs input], [Done], or [Error], including in Apple Terminal and cmux. Existing terminal-title settings still apply.

With notification mode terminal, Penguin selects the terminal's notification protocol: OSC 777 for cmux and WezTerm, OSC 9 for iTerm2 and Ghostty, and OSC 99 for Kitty. Apple Terminal and unrecognized terminals receive a bell; whether it sounds or marks the tab depends on terminal preferences. Notifications remain off by default. Focus-aware terminals suppress alerts while the selected session is focused; terminals without focus reporting may also alert while focused. Override detection with PENGUIN_TUI_NOTIFICATION_PROTOCOL=bell|osc9|osc99|osc777. cmux detection takes precedence over its underlying Ghostty identity. Notification details are enabled by default. Completion alerts include up to 240 characters of the final assistant response, with credential redaction. Reasoning and tool output are excluded. Disable details in /notifications to use generic alerts.

For an isolated smoke test, run these commands in separate terminals from penguin-tui/packages/opencode:

bun test/fixture/terminal-compat-server.ts
XDG_STATE_HOME="$(mktemp -d)" bun run --conditions=browser src/index.ts --url http://127.0.0.1:9010

Dismiss the provider picker, use /sessions, and select “Terminal compatibility test”. Then POST to http://127.0.0.1:9010/test/working, followed by /test/done or /test/error, and inspect the tab title. /test/question opens a question. Switch away from the TUI before completing a run to check background notifications. The fixture uses no provider or real sessions.

2. One-off prompts (non-interactive)

# Ask a single question (prints assistant reply and exits)
penguin-cli -p "Explain async/await in Python"

# Read the prompt from stdin (use "-" as the placeholder)
echo "Give me a limerick about penguins" | penguin-cli -p -

The following global flags can be combined with either interactive or non-interactive mode:

Flag	Description
`--model/-m <MODEL_ID>`	Override the model configured in penguin.yml
`--workspace/-w <PATH>`	Use a different workspace directory
`--no-streaming`	Disable token-by-token streaming output
`--fast-startup`	Skip memory indexing for faster launch
`--continue/-c`	Continue the most recent conversation in interactive mode
`--resume <SESSION_ID>`	Resume a specific saved conversation
`--run <TASK_NAME>`	Start autonomous execution for a specific task/project target
`--247 / --continuous`	Run continuously (24/7 mode); project-scoped runs work the ready frontier, while non-project runs may continue exploratorily
`--time-limit <MIN>`	Set an explicit CLI-supplied cap on RunMode duration
`--version/-V`	Print Penguin version and exit

/247 and --247 are intentionally different. /247 is an in-session alias for the durable /goal lifecycle described below. --247 (also --continuous) is a process-level CLI flag that starts continuous RunMode.

Sub-commands (Typer / headless CLI)

Most sub-commands are exposed through penguin-cli. If you are scripting Penguin, use that binary instead of assuming the interactive TUI launcher will behave like a classic CLI.

`project`

Project management helpers (backed by ProjectManager).

Command	Summary
`penguin-cli project create <NAME> [--description/-d TEXT]`	Create a new project using Penguin's managed default workspace
`penguin-cli project create <NAME> --workspace /exact/path`	Create a new project using the exact workspace path you provide
`penguin-cli project list`	List existing projects
`penguin-cli project delete <PROJECT_ID> [--force/-f]`	Delete a project

Workspace semantics for project creation:

--workspace uses the exact provided path. Penguin does not silently create a child directory under that path.
When --workspace is omitted, Penguin uses its managed default workspace path.
Project creation output distinguishes:
- Workspace (explicit): ...
- Workspace (default): ...
- Execution root: ...

Tasks are namespaced under a project:

Command	Summary
`penguin-cli project task create <PROJECT_ID> <TITLE>`	Create a task
`penguin-cli project task list [<PROJECT_ID>] [--status/-s STATUS]`	List tasks (optionally filtered)
`penguin-cli project task start <TASK_ID>`	Move task into the active state
`penguin-cli project task complete <TASK_ID>`	Approve a task that is pending review and mark it completed
`penguin-cli project task delete <TASK_ID> [--force/-f]`	Delete task

Status filters are case-insensitive and use the current task lifecycle values: active, running, pending_review, completed, failed, blocked, and cancelled.

`config`

Manage the Penguin configuration file and first-run setup wizard.

Command	What it does
`penguin-cli config setup`	Run (or re-run) the interactive setup wizard
`penguin-cli config edit`	Open the config file in your default editor
`penguin-cli config check`	Validate that required keys are present
`penguin-cli config test-routing`	Debug provider/model routing logic
`penguin-cli config debug`	Print an extended diagnostic report

`skill`

Discover, inspect, activate, and diagnose local Agent Skills.

Command	What it does
`penguin-cli skill list`	List discovered skills and surface a count of invalid skill diagnostics
`penguin-cli skill list --json`	Emit compact catalog and diagnostics as JSON
`penguin-cli skill show <NAME>`	Show the full `SKILL.md` body and metadata for a discovered skill
`penguin-cli skill show <NAME> --json`	Emit full skill metadata and body as JSON
`penguin-cli skill activate <NAME>`	Load the named skill into the current runtime session as `MessageCategory.CONTEXT`
`penguin-cli skill activate <NAME> --show-content`	Print the rendered `<skill_content>` activation payload after loading it
`penguin-cli skill doctor`	Validate discovered skill directories and print install guidance
`penguin-cli skill doctor --json`	Emit diagnostics as structured JSON

The default penguin launcher routes the skill subcommand to the same headless CLI path, so penguin skill list also works. For scripts and automation, prefer penguin-cli.

Manual install is currently folder-copy based: put skill directories containing SKILL.md under ~/.penguin/skills/<skill-name>/ for user skills or .penguin/skills/<skill-name>/ for trusted project skills. Package-manager install flows are deferred.

See Agent Skills for the runtime behavior and security model.

Developer utilities

Command	Purpose
`penguin-cli perf-test [-i N]`	Benchmark startup time with and without fast-startup
`penguin-cli profile [-o FILE] [--view]`	Launch Penguin under `cProfile` and save results
`penguin-cli chat`	Explicit synonym for starting interactive chat

In‑Chat Commands (Interactive Session)

When running penguin interactively, you can use slash‑style commands to control models, streaming, context, checkpoints, and Run Mode. Type /help to list all commands.

Models & Streaming

/models                 # Interactive model selector
/model set <MODEL_ID>   # Set a specific model (provider/model ID)
/stream on|off          # Toggle token streaming

Checkpoints & Branching

/checkpoint [name] [description]  # Save a conversation checkpoint
/checkpoints [limit]               # List checkpoints
/rollback <checkpoint_id>         # Restore to a checkpoint
/branch <checkpoint_id> [name]    # Branch a new conversation from a checkpoint

Context & Diagnostics

The /context command allows you to load documentation and reference files into the conversation. Files can be loaded from multiple locations:

Workspace context/ folder: The main location for context files in your workspace
Project root: Automatically discovers common documentation files (README.md, ARCHITECTURE.md, etc.)
Current directory: Any file in your current working directory

/context list                     # List available context files from all locations
/context load <file>              # Load a context file into conversation
/context add <file>               # Alias for /context load

Examples:

/context add architecture.md      # Load from project root or context/
/context load FILE_PICKER_FEATURE_PLAN.md  # Load from context/ folder
/context list                     # See all available files

Additional context management commands:

/context write|edit|remove|note   # Manage context artifacts
/context clear                    # Clear current context

Token Monitoring

/tokens                           # Token usage summary
/tokens detail                    # Detailed token breakdown
/truncations [limit]              # Recent context window trimming events

Session Goals

Session goals attach one durable objective to a persisted session. If /goal is entered before a TUI session exists, the TUI first creates and persists the session. An API or low-level caller must supply an existing session ID.

/goal <objective> [--replace]     # Save a goal and start execution
/goal status                      # Show objective, lifecycle state, and usage
/goal pause                       # Prevent another run; fence late completion
/goal resume                      # Mark active and resume execution
/goal run                         # Restart an active goal after a non-terminal return
/goal clear                       # Remove the persisted goal
/247 ...                          # Exact alias for the same /goal operation

/goal <objective> is not a prompt macro and is not continuous mode. It persists the objective, marks it active, and starts RunMode execution. Penguin does not impose iteration, wall-clock, or token limits when the user leaves them unset. Positive max_iterations, timeout_seconds, and cumulative goal token_budget values remain available as explicit controls, with no Penguin hard maximum. Token usage is checked between provider turns, so a final billed response may cross an explicitly configured budget before another turn is refused. Exhausting an explicit limit leaves durable non-complete state instead of pretending the goal finished.

An unfinished active, paused, blocked, usage_limited, or budget_limited goal must be replaced explicitly with --replace. A completed goal may be replaced directly. An in-flight run, a conflicting session request, or an illegal lifecycle transition is reported as a conflict rather than starting duplicate work.

/247 is branding for the same session-goal state and commands. It does not mean the --247 / --continuous CLI flag described above.

Run Mode (Autonomous Execution)

/run task "Name" [description]           # Start autonomous execution for a specific task target
/run continuous ["Name" [description]]   # Continuous Run Mode (public product-language alias: --247)
/run stop                                # Stop current Run Mode execution (if supported)

Current truth for continuous mode:

project-scoped runs work the ready frontier and may stop honestly when no tasks are ready
non-project runs may continue exploratorily by determining next steps
--time-limit currently represents an explicit CLI-supplied run cap; it should not be read as proof that blueprint/task-defined timing fields are fully surfaced through this CLI
session /goal and /247 commands do not enter this continuous loop; they execute one bounded task step at a time

When Run Mode needs human input, the interactive CLI now surfaces both:

clarification_needed status
clarification_answered acknowledgement

That keeps the pause/resume loop visible instead of making the CLI look stuck.

Examples

# Create a project and a task, then start the task
penguin-cli project create "Demo" -d "Playground project"

# Create a project with an explicit exact-path workspace
penguin-cli project create "Demo" --workspace /tmp/demo-workspace

# List projects and copy the ID from the table
penguin-cli project list

# Create and start a task (replace <PROJECT_ID> and <TASK_ID>).
# Task commands are namespaced under `project task`, not top-level `task`.
penguin-cli project task create <PROJECT_ID> "Research llama models"
penguin-cli project task list <PROJECT_ID>
penguin-cli project task start <TASK_ID>

Missing features

Earlier versions of the docs referenced commands such as `penguin memory`, `penguin db`, advanced task dependency graphs, and full web-server management. These features are work-in-progress and are not available in the current release. Attempting to run them will result in a "No such command" error.

Last updated: April 28, 2026 If you find inaccuracies, please open an issue.

Getting help​

Quick start​

1. Interactive chat (default TUI)​

2. One-off prompts (non-interactive)​

Sub-commands (Typer / headless CLI)​

project​

config​

skill​

Developer utilities​

In‑Chat Commands (Interactive Session)​

Models & Streaming​

Checkpoints & Branching​

Context & Diagnostics​

Token Monitoring​

Session Goals​

Run Mode (Autonomous Execution)​

Examples​

Missing features​

Earlier versions of the docs referenced commands such as penguin memory, penguin db, advanced task dependency graphs, and full web-server management. These features are work-in-progress and are not available in the current release. Attempting to run them will result in a "No such command" error.​