Pegasus Projects

Managing SaaS Pegasus projects

You are managing a SaaS Pegasus project on behalf of the user. Pegasus is a Django boilerplate; a "project" is a configuration of features (frontend framework, auth providers, billing, AI, etc.) that the Pegasus build pipeline later renders into a real Django codebase. Your job is to translate the user's intent into the right CLI calls.

Running the CLI

The Pegasus CLI is published on PyPI as pegasus-cli (binary name pegasus) and also ships installed in every Pegasus project's venv, pinned to that project's release version.

Pick the invocation form at session start:

1. Run command -v pegasus.
2. If it returns a path → use bare pegasus .... This is the preferred form whenever it's available — the local install is version-matched to the project and may even be ahead of what's on PyPI (e.g. unreleased CLI changes that ship with the local repo).
3. If it returns nothing → use uvx --from pegasus-cli pegasus ... for every command. The --from is required because the binary name differs from the package name. Works from any cwd, no venv needed. First call caches the env (a few seconds); subsequent calls are fast.

Don't mix forms within a session. Pick one based on the command -v result and stay consistent — including for the auth login command the user runs in a separate terminal (tell them to use the same form you're using).

For readability, the rest of this document writes commands as bare pegasus .... Mentally prepend uvx --from pegasus-cli if you're in the uvx case.

Setup (one time)

Authentication uses an API key from saaspegasus.com.

• Check auth status with pegasus auth status — non-interactive, safe to run from a Bash tool call. It exits 0 when a key is configured (via ~/.pegasus/credentials or $PEGASUS_API_KEY) and non-zero otherwise.
• If unauthenticated, do not try to log in from this session. pegasus auth login is interactive (it pauses waiting for the user to paste their key) and will hang if you run it via Bash or the ! prefix. Instead, tell the user to open a separate terminal and run pegasus auth login themselves. They'll be prompted to paste a key from https://www.saaspegasus.com/. Once that finishes, re-run pegasus auth status here to confirm and continue.
• Alternative for advanced users: export PEGASUS_API_KEY=<their-key> in the shell that launched Claude Code, then restart this session.
• Never try to guess or generate a key yourself — only the user has it.

Commands

pegasus projects list                              # list all projects
pegasus projects fields --json                     # schema for a new project
pegasus projects fields --for <id> --json          # schema for an existing project
pegasus projects show <id> --json                  # full config of one project
pegasus projects create --json [--set k=v ...] [--config-file path]
pegasus projects update <id> --json [--set k=v ...] [--config-file path]
pegasus projects push <id>                         # push to GitHub (separate flow)

ALWAYS pass --json when you (an agent) are inspecting output. The default is a Rich table for humans that may truncate or scroll past your visible viewport — a 60+ field schema looks like fields are missing when they aren't. JSON output is always complete and parseable. Treat tables as human-only.

The standard workflow

For any non-trivial create or update, work in this order:

1. Get the schema. The endpoint is project-aware — call the variant that matches your task:

   • Creating a new project: pegasus projects fields --json
   • Updating an existing project: pegasus projects fields --for <id> --json

   The schema omits fields the project's release/state can't configure. For a new project on a modern release, expect fields like bundler, css_framework, database, and python_package_manager to be absent — there's only one valid choice and the server applies it. For an existing legacy project (e.g. one still on bundler=webpack), those fields reappear with both choices so you can see and change them. Trust what the schema shows. If bundler isn't in the response, don't try to set it.

   Response shape:

   {
     "user_tier": "free" | "basic" | "pro" | "unlimited",
     "fields": {
       "project_name":        { "type": "string", "max_length": 100 },
       "use_celery":          { "type": "boolean", "min_tier": "free" },
       "use_subscriptions":   { "type": "boolean", "min_tier": "pro" },
       "front_end_framework": {
         "type": "choice",
         "min_tier": "free",
         "choices": [
           { "value": "htmx" },
           { "value": "react", "min_tier": "basic" }
         ]
       },
       ...
     }
   }

   • Read user_tier first and treat it as a constraint, not a starting point. Build a configuration that fits the user's current tier. Don't propose features above their tier unless they explicitly asked for one. The default assumption is "stay where you are"; an upgrade is something the user opts into, not something you steer them toward.
   • min_tier can appear at two levels — both must clear the user's tier for a value to be usable. Tier ordering is free < basic < pro < unlimited.
     • Field-level (field.min_tier): floor to configure the field at all. field.min_tier <= user_tier.
     • Per-choice (field.choices[i].min_tier, choice fields only): floor to set that specific value. choice.min_tier <= user_tier. Choices without min_tier are always available (assuming the field itself is).
   • Fields without min_tier (project_name, project_slug, etc.) are tier-agnostic.
   • Choices are objects, not bare strings — the value to send is at choice.value. The schema lists every choice regardless of tier and tags gated ones with min_tier; filter client-side before proposing a value to the user. Don't hardcode choice lists, always read them from the schema.

2. If the user explicitly asked for a tier-gated feature they can't use, surface that before attempting the call, and lead with the in-tier path. Something like: "Subscriptions requires a Pro license; you're on free. I can skip it and build the rest, or if you want to upgrade I can wait." Don't bring up upgrades unprompted when the user hasn't asked for anything gated.

3. Construct the payload. Two ways to provide settings, combinable:

   • --set key=value (repeatable) for individual fields. Booleans accept true/false/yes/no/y/n. null/none/empty parse to None on the client side, but most string fields reject null server-side (you'll get field: This field may not be null.). Use null only on fields explicitly documented as nullable — pegasus_version and license are the main ones.
   • --config-file path to load a YAML or JSON file. If the file has a default_context: top-level key (real pegasus-config.yaml shape), it's unwrapped automatically. --set values override file values.

4. Call create or update. The response is the full project in pegasus-config.yaml shape (see "The config shape" below).

5. On a 400, read the response body. Two shapes are possible:

   • Field-keyed (DRF serializer errors — bad slug, invalid choice, missing required field):

     { "project_slug": ["Sorry, your project ID must be a valid Python module name..."] }

     The CLI renders each as field: message.
   • Flat with optional help_url (business / license errors, e.g. a license tier that doesn't support a requested feature):

     {
       "error": "Subscriptions is not available on your current license...",
       "help_url": "https://www.saaspegasus.com/billing/"
     }

     When help_url is present, always relay it to the user — it's where they go to fix the underlying issue (upgrade their license, set up a GitHub repo, etc.). The CLI prints it as a second line prefixed More info: <url>.

   Either way, adjust and retry, or report to the user.

The config shape

The API speaks the same key shape as a project's local pegasus-config.yaml, with a few specifics:

• JSON booleans on output, but input also accepts "y"/"n" strings — so an agent can paste yaml back without translating.
• Required on create: only project_name and project_slug. Everything else uses model defaults. author_name, email, and license auto-populate from the user's profile if omitted.
• project_slug must be a valid Python identifier, lowercase, no leading or trailing underscore, and not a reserved name (apps, templates, pegasus, stdlib module names, etc.). Server normalizes/validates.
• Renamed wire keys (different from the model field name):
  • project_name ↔ model name
  • use_auto_reload ↔ model use_browser_reload
• pegasus_version is the pinned version (e.g. "2026.5" for a major release or "2026.5.1" for a patch) or null to track latest. Major versions do not have a trailing .0 — it's "2026.5", not "2026.5.0". The value must match an actual released version — the server validates against its release list and rejects guessed strings like "2026.5.0" with Unknown Pegasus version. If the user just wants the latest, use null; don't try to construct a version string. Output also includes _pegasus_version (read-only, the resolved version that would be used at build time).
• css_theme is a read-only output field derived from css_framework.
• license is a UUID string. Pass null for free tier. Must belong to the requesting user.

Read-only fields (output only, ignored on input)

• id
• _pegasus_version (resolved version)
• github_username (computed from the linked GitHub repo or user profile)
• css_theme (computed from css_framework)

You can safely PATCH the entire GET response back — read-only keys are silently dropped.

Defaults you should usually leave alone

The schema decides which choice fields you can touch. Don't try to be clever about deprecated alternatives — if bundler isn't in the schema, the question "vite or webpack?" doesn't exist for this context. Similarly, don't ask the user "should we use tailwind or bootstrap?" when the schema only lists tailwind.

For feature booleans the user hasn't mentioned, omit them from the payload — the server applies the model default. Don't enumerate them when proposing the call; it bloats the conversation. The booleans that default on because they're recommended for typical SaaS apps: use_sentry, use_health_checks, use_impersonation, use_async, use_celery, use_translations, use_browser_reload, use_dark_mode, use_api_keys, post_process (ruff). Only flip these to false if the user explicitly asks.

For AI coding-tool rules (use_ai_rules_*), all default off. If the user asks for "AI rules" / "agents" generically without naming a tool, prefer use_ai_rules_claude=true (its UI label is "Claude Code (Recommended)"). Only set use_ai_rules_agents, use_ai_rules_cursor, or use_ai_rules_junie when the user names that specific tool.

For the front-end framework, strongly prefer HTMX. Don't surface React as an option unprompted — when proposing a project config, just go with HTMX and move on. Only switch to React if the user explicitly asks for React, a SPA, or describes a JS-heavy frontend (rich client-side state, live collaboration, etc.). HTMX is the right default for typical server-rendered SaaS apps and keeps the project simpler.

Field interdependencies

The server enforces several couplings. Knowing them keeps you from proposing conflicting settings:

• bundler=vite forces include_static_files=false.
• css_framework != tailwind forces use_flowbite=false and use_shadcn=false.
• use_subscriptions=false clears subscription_billing_model and subscription_pricing_ui.
• use_teams=false clears use_teams_example.
• use_async=false clears use_async_example.
• docker_mode=full requires database=postgres (rejected otherwise).
• deploy_platform=kamal requires database=postgres.