Skip to main content

What's New

Stay up to date with the latest Fastman releases and features.

v0.3.6 (Cheetah) — March 2026​

Safer Keycloak startup, non-destructive SSL certificate handling, and clearer admin credential guidance

install:cert Command​

The certificate utility is now modeled around merged CA bundles instead of patching certifi.

  • New primary command: fastman install:cert
  • It builds certs/ca-bundle-merged.pem from certifi plus your project certificates
  • It writes CERTS_PATH, REQUESTS_CA_BUNDLE, and SSL_CERT_FILE into env files when needed
  • install:certificate remains as a deprecated alias for compatibility

Graceful Keycloak Startup​

Keycloak integration no longer takes your whole app down when the identity provider is unavailable during startup.

  • If KEYCLOAK_URL is unreachable, Fastman logs the error, disables Keycloak for that boot, and still starts the API
  • /health and other non-Keycloak routes stay available
  • Protected routes continue to work as soon as Keycloak is configured correctly and the app is restarted

Public Client Compatibility​

If Keycloak returns unauthorized_client while trying to obtain an admin token, Fastman now treats that as an admin-only limitation instead of a fatal boot error.

  • Basic auth flows still work: Swagger authorize, Depends(get_current_user), and GET /me
  • Admin features are disabled until you provide a confidential admin client with service accounts enabled
  • KEYCLOAK_ADMIN_SECRET is now documented as optional for projects that do not use admin API methods

Non-Destructive SSL Certificate Support​

Fastman no longer edits the installed certifi bundle in place for generated Keycloak projects.

  • init_keycloak() builds a merged CA bundle from certifi plus project certificates
  • It sets REQUESTS_CA_BUNDLE and SSL_CERT_FILE for the running process
  • Projects with no certs/ directory remain unaffected

v0.3.4 (Cheetah) — March 2026​

Persistent env switching, configurable docs, public directory, and Keycloak Swagger auth

Persistent Environment Switching​

Use fastman env --source= to lock an environment. All subsequent fastman serve calls will use it automatically — no --env flag needed.

# Lock to development
fastman env --source=development

# Now serve uses .env.development automatically
fastman serve

# Check what's active
fastman env

# Clear the lock, return to auto-detect
fastman env --reset

The selection is stored in .fastman (add to .gitignore). You can always override temporarily with fastman serve --env=staging.

Configurable Documentation URLs​

Swagger and Redoc paths are now configurable via settings instead of hardcoded:

# .env
DOCS_URL=/docs
REDOC_URL=/redoc

Set to empty to disable: DOCS_URL= disables Swagger UI. In production, docs are automatically disabled when DEBUG=false.

Public Directory​

All scaffold patterns now include a public/ directory, mounted at /public for serving static files:

my-api/
├── app/
├── public/          # Static files (HTML, images, CSS, JS)
│   └── index.html
├── certs/
└── .env

Configure the directory name in .env:

PUBLIC_DIR=public

Keycloak: Switched to fastapi-keycloak​

Keycloak authentication now uses fastapi-keycloak instead of fastapi-keycloak-middleware. Key changes:

  • Dependency injection — routes are protected via Depends(get_current_user) instead of global middleware
  • GET /me endpoint — automatically registered, returns the current OIDC user
  • Swagger Authorize button — idp.add_swagger_config(app) adds OAuth2 auth to Swagger UI
  • User & role management — the FastAPIKeycloak instance (idp) exposes methods for creating/deleting users, roles, and groups
  • New env variables: KEYCLOAK_ADMIN_SECRET, KEYCLOAK_CALLBACK_URI

Lazy Keycloak Initialization & Auto Certificate Appending​

The FastAPIKeycloak instance is now lazy-initialized inside init_keycloak(app) instead of at module import time. This solves SSL verification failures that occurred when the IDP tried to contact Keycloak during import.

At startup, init_keycloak() automatically:

  1. Scans certs/ (or CERTS_PATH) for .pem/.crt files and builds a merged CA bundle
  2. Sets REQUESTS_CA_BUNDLE and SSL_CERT_FILE for the running process
  3. Creates the FastAPIKeycloak instance — HTTPS calls now trust your custom certificates
  4. Configures Swagger OAuth and registers the /me endpoint

No separate certificate script is needed — just drop your cert files in certs/ and start the server.

Graceful Keycloak Fallback​

The app no longer crashes if Keycloak is unreachable or misconfigured:

  • Connection refused (Keycloak not running): the app starts with Keycloak disabled, logs a warning, and /health still responds
  • Public client (unauthorized_client): the app starts with admin features (user/role management) disabled — basic auth still works
  • Valid Keycloak: full functionality including admin features and Swagger Authorize button

Certificate Path Fixes​

  • fastman install:certificate now shows the resolved certificate directory and target CA bundle paths
  • fastman env displays certificate paths and certifi CA bundle location

v0.3.2 (Cheetah) — March 2026​

Environment-aware serve, certifi auto-install, and Keycloak SSL resilience

Environment-Aware Serve​

You can now choose which .env file to load when starting the development server:

fastman serve --env=development
fastman serve --env=staging
fastman serve --env=production

When --env is omitted, Fastman auto-detects .env.production if it exists, otherwise .env.

certifi Auto-Install​

fastman install:certificate now installs certifi in the project's venv automatically if it's not already present. No more manual pip install certifi.

Keycloak SSL Resilience​

The generated keycloak.py now validates all certificate paths before passing them to verify=. If a path is missing, it falls back gracefully to system defaults with a clear log message instead of crashing with FileNotFoundError.

v0.3.1 (Cheetah) — March 2026​

Keycloak certificate support and documentation refresh

Certificate Management for Keycloak and Private Services​

Fastman can now trust project-local certificates for Keycloak and other third-party services that use private CAs.

fastman install:auth --type=keycloak --append-certificate

# or run certificate setup independently
fastman install:certificate

Add your .pem or .crt files to the project's certs/ directory and Fastman appends them to the Python certifi CA bundle.

Documentation Refresh​

  • Updated the command reference to include install:certificate and --append-certificate
  • Renamed the relevant command grouping to third-party integrations
  • Refreshed README, intro, installation, and auth concept docs for v0.3.1 (Cheetah)

v0.3.0 — March 2026​

Passkey authentication, full OAuth scaffolding, and IPython out of the box

Passkey (WebAuthn) Authentication​

No passwords, no MFA. Users authenticate with their fingerprint, Face ID, hardware security key, or device PIN.

fastman install:auth --type=passkey

Generates a complete authentication module with registration and login flows using the WebAuthn standard. After authentication, users receive a JWT session token — same as other auth types.

Endpoints created:

  • POST /auth/passkey/register/options — Get registration challenge
  • POST /auth/passkey/register/verify — Store new passkey
  • POST /auth/passkey/authenticate/options — Get login challenge
  • POST /auth/passkey/authenticate/verify — Verify & get session token
  • GET /auth/passkey/me — Current user info
  • GET /auth/passkey/credentials — List registered passkeys
  • DELETE /auth/passkey/credentials/{id} — Remove a passkey

Full OAuth Scaffolding​

OAuth is no longer a stub. It now generates a complete feature module with provider-specific configuration:

fastman install:auth --type=oauth --provider=google
fastman install:auth --type=oauth --provider=github
fastman install:auth --type=oauth --provider=discord

Each provider comes pre-configured with the correct authorize URL, token URL, userinfo endpoint, and scopes. The generated code includes user creation/update on callback, session management, and logout.

IPython Included by Default​

ipython is now a required dependency. fastman tinker launches an IPython shell immediately — no extra install step needed.

Other Changes​

  • Fixed cross-browser CSS issues in docs site (Safari backdrop-filter, Firefox mask)
  • Fixed install:auth syntax in all documentation (positional → --type= option)
  • Updated authentication docs with comparison table and passkey guide

v0.2.6 — March 2026​

Virtualenv compatibility, Oracle driver update, and progress bar

This release fixes the most common issues new developers hit when starting their first project.

If you're upgrading​

# With uv
uv tool upgrade fastman

# With pip
pip install --upgrade fastman
Already have an existing project?

If fastman serve fails with Extra inputs are not permitted, add extra = "ignore" to your Settings.Config class in app/core/config.py. New projects include this automatically.

Server & tooling now work inside virtual environments​

The biggest change: all external tool calls (uvicorn, alembic, black, isort, autoflake, pytest, mypy) now use python -m <tool> instead of calling the bare command. This means commands work correctly inside virtualenvs even when the tool's binary isn't on your PATH.

Before (v0.2.0):

$ fastman serve
# Internally ran: uvicorn app.main:app ...
# ❌ "uvicorn: command not found" inside some venvs

$ fastman database:migrate
# Internally ran: alembic upgrade head
# ❌ "alembic: command not found"

After (v0.2.6):

$ fastman serve
# Internally runs: python -m uvicorn app.main:app ...
# ✅ Always works

$ fastman database:migrate
# Internally runs: python -m alembic upgrade head
# ✅ Always works

Affected commands: serve, make:migration, database:migrate, migrate:rollback, migrate:reset, migrate:status, optimize, build

Oracle driver updated​

cx_oracle is deprecated. New Oracle projects now use oracledb:

# Before
DATABASE_URL=oracle+cx_oracle://user:pass@localhost:1521/XE

# After
DATABASE_URL=oracle+oracledb://user:pass@localhost:1521/XE

The pip dependency also changed from cx_Oracle to oracledb.

Extra .env variables no longer crash the server​

When you choose Oracle, PostgreSQL, or MySQL, the generated .env includes convenience variables (ORACLE_USER, POSTGRES_PASSWORD, etc.). Previously these caused a Pydantic ValidationError because the Settings class didn't declare them:

ORACLE_USER
  Extra inputs are not permitted

Fix: The generated config now uses environment-aware loading with extra = "ignore":

def _get_env_file() -> str:
    env = os.getenv("ENVIRONMENT", "development")
    env_file = f".env.{env}"
    if Path(env_file).exists():
        return env_file
    return ".env"

class Config:
    env_file = _get_env_file()
    case_sensitive = True
    extra = "ignore"

Multi-environment support​

Projects now generate four environment files:

  • .env — Fallback defaults
  • .env.development — Local dev settings (DEBUG=true, localhost)
  • .env.staging — Staging settings (staging DB host)
  • .env.production — Production settings (DEBUG=false, restricted hosts)

The ENVIRONMENT variable controls which file is loaded. All fastman commands that modify env vars (auth, key:generate, etc.) update all env files automatically.

Per-provider database settings​

Database configuration now uses individual fields instead of a single DATABASE_URL:

DB_HOST: str = "localhost"
DB_PORT: int = 5432
DB_USER: str = "postgres"
DB_PASSWORD: str = ""
DB_NAME: str = "myapp"

@computed_field
@property
def database_url(self) -> str:
    return f"postgresql://{self.DB_USER}:{self.DB_PASSWORD}@{self.DB_HOST}:{self.DB_PORT}/{self.DB_NAME}"

You can still set DATABASE_URL directly to override the computed value.

Progress bar for fastman create​

Project creation now shows a single real-time progress bar instead of printing individual file/directory creation messages:

⠋ Setting up project directories...  ━━━━━━━━━━━╺━━━━━━━━━  30%

New and updated flags​

Several flags that were already implemented in the CLI are now fully documented, exposed in --help output, and included in shell completions.

fastman create — --graphql and --minimal flags​

# Scaffold a project that includes GraphQL support out of the box
fastman create gql-api --graphql

# Skip optional dev dependencies (faker, pytest, httpx)
fastman create tiny-api --minimal
  • --graphql generates app/core/graphql.py and adds strawberry-graphql[fastapi] to dependencies.
  • --minimal omits faker, pytest, and httpx from dependencies.

fastman serve — explicit --reload flag​

--reload is now an explicit flag alongside the existing --no-reload. The default behaviour (reload enabled) is unchanged.

fastman serve --reload      # explicit; same as default
fastman serve --no-reload   # disable reload for production-like runs

fastman activate — --create-script flag now visible​

--create-script was already implemented but not shown in --help. It now appears in the usage line:

fastman activate --create-script

Creates a small helper script (activate.sh / activate.bat) in the project directory alongside printing the activation command.

fastman make:api — correct flag is --style​

The flag to choose between REST and GraphQL output has always been --style (not --type). The docs now reflect this correctly:

fastman make:api orders --style=rest      # default
fastman make:api orders --style=graphql

fastman install:auth — --provider option​

An optional --provider value can be passed for OAuth flows:

fastman install:auth --type=oauth --provider=google

fastman docs and fastman completion — flags now in help​

fastman docs --open            # open the docs site in your browser
fastman completion bash --install  # install completion, not just print it

Other fixes​

AreaWhat changed
pip on WindowsVenv pip path now resolves correctly (.venv\Scripts\pip.exe)
Package manager detectionFalls back to pip when uv isn't installed; detects requirements.txt-only projects
fastman create on existing dirNow exits with code 1 instead of silently returning
Banner renderingGracefully handles missing/corrupt Pyfiglet fonts
Docker CMDGenerated Dockerfile uses python -m for alembic and uvicorn

v0.2.0 — February 2026​

Professional console UI, shell completions, and virtual environment management

The first major update after the initial release, focused on developer experience.

Professional Console UI​

All CLI output is now styled with Rich (when installed), with Laravel-inspired aesthetics:

> Project 'my-api' created successfully!

>> Next steps:
  cd my-api - Navigate to project directory
  fastman serve - Start the development server
  fastman list - View all available commands

New methods available for custom commands: Output.section(), Output.task(), Output.listing(), Output.highlight(), Output.comment(), Output.ask(), Output.choice(), Output.confirm(), Output.progress(), Output.spinner()

Shell completions​

Tab completion for all commands and options. Install with one command:

fastman completion bash --install   # Bash
fastman completion zsh --install    # Zsh
fastman completion fish --install   # Fish
fastman completion powershell --install  # PowerShell

Virtual environment activation​

Don't remember the activation command for your OS? Just run:

fastman activate
# Shows: source .venv/bin/activate    (Linux/Mac)
# Shows: .\.venv\Scripts\activate     (Windows)

29 integration tests​

Real filesystem tests (not mocks) covering project creation, feature scaffolding, utilities, template rendering, and CLI behaviour.

Bug fixes​

  • pyproject.toml syntax error fixed
  • All subprocess calls have timeouts (30–300 s)
  • CLI option parsing handles both --name=value and --name value
  • File operations handle PermissionError and IsADirectoryError specifically
  • Path traversal protection
  • Secure key generation via secrets.token_urlsafe()

v0.1.0 — January 2026​

Initial release — 30+ commands for FastAPI development.

Project & scaffolding​

fastman create my-api --pattern=feature --database=postgresql
fastman make:feature users --crud
fastman make:model post
fastman make:service payment
fastman install:auth --type=jwt

Database & migrations​

fastman make:migration "create users table"
fastman database:migrate
fastman migrate:rollback --steps=2
fastman database:seed

Dev tools​

fastman serve              # Start dev server with hot reload
fastman tinker             # Interactive shell with DB session
fastman route:list         # Show all API routes
fastman config:appkey      # Generate SECRET_KEY
fastman optimize           # Run black + isort + autoflake

Highlights​

  • Rich & Pyfiglet included — Styled output and banners out of the box
  • Smart package detection — Auto-detects uv, poetry, pipenv, or pip
  • 5 databases — SQLite, PostgreSQL, MySQL, Oracle, Firebase
  • 3 architecture patterns — Feature (vertical slices), API, Layer (MVC-style)
  • Auth scaffolding — JWT, OAuth, Keycloak