Skip to content

CLI overview

What it is / when to use it

PenguiFlow ships a CLI to bootstrap agent projects, run the playground, and validate ToolNode presets:

  • penguiflow new scaffolds a project from templates
  • penguiflow dev runs the playground (backend + UI) for a project
  • penguiflow init generates VS Code helpers (.vscode/*)
  • penguiflow generate generates an agent workspace from a YAML spec
  • penguiflow tools lists/connects ToolNode presets and can discover tool names

Use the CLI when you want a repeatable “scaffold → run → iterate” loop and you want to avoid bespoke glue code on day 1.

Non-goals / boundaries

  • The CLI is not a deployment system; production concerns live in Deployment.
  • The CLI is not a secrets manager; keep secrets in env/secret managers (never in committed YAML).
  • penguiflow tools connect --discover is a connectivity check, not a production configuration workflow.

Contract surface

  • Installed command: penguiflow (see penguiflow --help)
  • Required extras:
  • penguiflow new / penguiflow generate require jinja2 (install penguiflow[cli] or penguiflow[dev])
  • penguiflow tools discovery requires penguiflow[planner]

Workflow A: scaffold a project, then run playground

uv run penguiflow new my-agent --template react
cd my-agent
uv sync
uv run penguiflow dev --project-root .

Workflow B: spec-first generation (declarative)

uv run penguiflow generate --init my-agent
cd my-agent
# edit my-agent.yaml
uv run penguiflow generate --spec my-agent.yaml
uv run penguiflow dev --project-root .

Workflow C: validate ToolNode connectivity

uv run penguiflow tools list
uv run penguiflow tools connect github --discover

Failure modes & recovery

  • penguiflow new fails with “Jinja2 is required”: install penguiflow[cli] (or jinja2).
  • penguiflow dev fails with missing UI assets (repo checkout): build UI assets under penguiflow/cli/playground_ui.
  • penguiflow tools fails with “penguiflow[planner] is required”: install penguiflow[planner].
  • Environment mismatch in playground: the playground runs in penguiflow’s Python environment, not the agent project’s venv (see penguiflow dev).

Observability

  • penguiflow dev runs a local server; use standard logs and /health for basic checks.
  • Runtime/Planner observability is described in:
  • Logging
  • Telemetry patterns

Security / multi-tenancy notes

  • Don’t commit .env files; treat them as secrets.
  • Keep tool auth in environment variables and secret managers, not in generated code.

Troubleshooting checklist

  • Start by running: penguiflow --help and the subcommand --help.
  • If something works in CI but not locally, validate which venv is running penguiflow (which penguiflow, python -c ...).