fastmvc-cli 1.5.0

FastMVC CLI — interactive FastAPI project generator and tooling

fastmvc-cli

FastMVC CLI — a console toolkit for generating FastAPI / FastMVC projects, scaffolding APIs, running database migrations, and maintaining a few operational utilities.

Install from PyPI as fastmvc-cli (the name fast-cli on PyPI is a separate project you do not control). After install, use the fast command (shortest), or fast-cli / fastmvc scripts — same as before.

---

Contents

• Install
• Global options
• Command map
• Project generation
• Scaffolding (add)
• Environment (env)
• Database migrations (db)
• Documentation (docs)
• Caching (cache)
• Background tasks (tasks)
• Cleanup (decimate)
• Commit history (setup-commit-log)
• Legacy (make)
• Related repositories
• Layout
• Publishing to PyPI

---

Install

pip install fastmvc-cli

Interactive prompts (wizard-style flows) use Questionary. Install it for the full experience:

pip install "fastmvc-cli[interactive]"

For development and tests:

pip install "fastmvc-cli[dev]"

Requires Python 3.10+.

---

Global options

Option	Description
--version	Print the package version and exit.
--help	Show help for the root group or any subcommand.

Discover everything at once:

fast --help
fast <command> --help

---

Command map

Area	Command	Purpose
Projects	generate, new, quickstart	Create a new FastMVC-style project (interactive or flags).
Scaffold	add resource	Add a versioned API operation (DTOs, repo, service, controllers).
Env	env	Generate .env from .env.example in the current project.
DB	db migrate, upgrade, downgrade, reset, history, status	Alembic wrappers (run from a directory with alembic.ini).
Docs	docs generate, docs deploy	Generate MkDocs-style reference stubs; deploy with mkdocs gh-deploy.
Cache	cache clear, cache invalidate	Clear or tag-invalidate FastCaching (requires fast_caching).
Tasks	tasks worker, list, status, dashboard	FastTasks / fast_platform workers (optional).
Cleanup	decimate	Delete build/cache artifacts under a path.
Repo tooling	setup-commit-log	Install commit-history recorder + pre-commit hook in any git repo.
Legacy	make	Deprecated; forwards to add or env.

---

Project generation

Commands: generate, new (alias), quickstart.

Behavior

• generate / new: If you pass both --name and --path, the CLI runs non-interactively from those options. If either is missing, it starts the interactive generator.
• quickstart: Creates a project with defaults (project name defaults to my_fastapi_project unless you set --name).

Options (generate / new)

Option	Shorthand	Default	Description
--name	-n	—	Project name.
--path	-p	—	Target directory (use . for current dir).
--author	-a	—	Author name.
--email	-e	—	Author email.
--description	-d	—	Short project description.
--version	-v	0.1.0	Initial project version string.
--venv / --no-venv	—	venv on	Create a virtual environment.
--venv-name	—	.venv	Virtualenv directory name.
--install-deps / --no-install-deps	—	install on	Install dependencies after generation.

Options (quickstart)

Option	Default	Description
--name	my_fastapi_project	Project name.
--venv-name	.venv	Virtualenv directory name.
--install-deps / --no-install-deps	install on	Install dependencies after generation.

Examples

fast generate
fast new --name my_api --path ./my_api
fast quickstart --name demo_api

---

Scaffolding (add)

Command: add resource.

Scaffolds a single versioned operation in an existing FastMVC layout: request/response DTOs, repository, service, dependency provider, core controller, and FastAPI-facing API controller. The CLI must find abstractions/controller.py at the resolved project root.

Options

Option	Shorthand	Required	Default	Description
--folder	-f	yes	—	Folder segment (e.g. user, auth).
--resource	-r	yes	—	Operation name (e.g. fetch, create).
--version	-v	no	v1	API version (v1, v2, …).
--crud / --no-crud	—	no	CRUD on	Reserved for future template variants.

Example

cd /path/to/your/fastmvc/project
fast add resource --folder user --resource create --version v1

---

Environment (env)

Command: env.

Generates a .env file from .env.example at the resolved FastMVC project root. Fails if .env already exists or .env.example is missing (see ProjectBootstrap in the codebase).

fast env

---

Database migrations (db)

Group: db. These commands are thin wrappers around the alembic CLI. Run them from a project directory that contains alembic.ini (typical FastMVC layout). Install Alembic in that environment: pip install alembic.

db migrate

Create a new revision.

Option	Shorthand	Description
--message	-m	Required. Migration message.
--autogenerate / --no-autogenerate	—	Autogenerate from models (default: on).

fast db migrate -m "Add users table"

db upgrade

Apply migrations.

Option	Shorthand	Default	Description
--revision	-r	head	Revision to upgrade to.

fast db upgrade
fast db upgrade -r head

db downgrade

Rollback migrations.

Option	Shorthand	Default	Description
--revision	-r	-1	Target revision (default one step back).

Confirms before running (Questionary or Click confirm).

db reset

Destructive: drops all tables (downgrade to base) and reapplies migrations to head.

Option	Description
--seed / --no-seed	If --seed, runs scripts/seed.py when present.

Requires typing RESET to confirm.

db history

Show migration history.

Option	Shorthand	Description
--verbose / --no-verbose	-v	More detail from alembic history.

db status

Show current revision, heads, and whether migrations are pending.

---

Documentation (docs)

Group: docs.

docs generate

Walks apis/ and dtos/ and writes Markdown under docs/api/ (e.g. endpoints.md, dtos.md, optional ecosystem.md for sibling fast_* packages). Uses mkdocstrings-style ::: directives for a later MkDocs build.

fast docs generate

docs deploy

Runs mkdocs gh-deploy with an optional commit message.

Option	Shorthand	Default
--message	-m	Deploy documentation

fast docs deploy -m "Update API docs"

---

Caching (cache)

Group: cache. Requires the fast_caching package importable in your environment.

cache clear

Purge all resident cache data via the backend.

cache invalidate

Invalidate by tag names.

fast cache invalidate user-list product-cache

---

Background tasks (tasks)

Group: tasks. Uses fast_platform task APIs when available.

Command	Description
tasks worker	Start a background worker. --concurrency / -c (default 10).
tasks list	List registered task definitions.
tasks status <task_id>	Show status for one job.
tasks dashboard	Live table (refresh --refresh / -r ms, default 1000). Ctrl+C to exit.

fast tasks worker -c 8
fast tasks dashboard -r 2000

---

Cleanup (decimate)

Command: decimate [LANGUAGE] [PATH].

Destructive: removes build/cache artifacts matching built-in patterns. Defaults: language python, path ..

Supported language keys include python, java, rust (see ARTIFACTS_BY_LANGUAGE in fast_cli.constants). Virtualenv directories such as .venv are skipped during traversal.

fast decimate python .
fast decimate rust ./my-crate

---

Commit history (setup-commit-log)

Command: setup-commit-log.

Installs the bundled git_log_recorder.py into _maint/scripts/, merges a local pre-commit hook into .pre-commit-config.yaml (post-commit stage), and ensures .gitignore lists:

• coverage_output.txt
• commit_history.json

Option	Description
-C, --path	Git repository root (default: current directory).
--install-hooks / --no-install-hooks	Run pre-commit install and pre-commit install --hook-type post-commit (default: install).
--with-common-hooks	When creating a new .pre-commit-config.yaml, also add common hooks (trim whitespace, YAML/JSON checks, etc.).

fast setup-commit-log
fast setup-commit-log -C /path/to/repo --no-install-hooks
fast setup-commit-log --with-common-hooks

If you skip automatic install:

pip install pre-commit
pre-commit install
pre-commit install --hook-type post-commit

Each commit appends metadata to commit_history.json at the repository root.

---

Legacy (make)

Command: make <resource|env>.

Deprecated. Use add or env instead.

• make resource <name> forwards to add resource with fixed defaults.
• make env invokes env.

---

Related repositories

FastMVC framework (sibling checkout)	../fast_mvc
GitHub	github.com/shregar1/fast.mvc

This repo’s package metadata references github.com/fastmvc/fast.cli. The PyPI distribution is fastmvc-cli.

---

Publishing to PyPI

The PyPI project name is fastmvc-cli (name in pyproject.toml). Create it under your PyPI account on first successful upload. Bump __version__ in fast_cli/__init__.py before each release.

If you see 403 Forbidden and a message like isn’t allowed to upload to project some-name: that PyPI project already exists and belongs to someone else, or your token is not scoped for it. Use a distribution name you own (this repo uses fastmvc-cli) or ask the project owner to add you as a maintainer.

Publishing uses a PyPI API token only (no password login). Create one under PyPI → Account settings → API tokens.

Local build and upload

Install build tools (included in the dev extra):

pip install "fastmvc-cli[dev]"   # or: pip install build twine
python -m build               # writes dist/fast_cli-*.tar.gz and .whl
twine check dist/*

Upload with your token. The username must be exactly __token__; the password is the full token (including the pypi- prefix):

export TWINE_USERNAME=__token__
export TWINE_PASSWORD='pypi-AgEIcHlwaS5vcmc...'   # paste your token
twine upload dist/*

On one line:

TWINE_USERNAME=__token__ TWINE_PASSWORD='pypi-…' twine upload dist/*

Never commit the token or add it to the repo—use shell exports, a password manager, or CI secrets only.

GitHub Actions

The workflow .github/workflows/publish-pypi.yml runs when you push a tag matching v* (for example v1.5.1).

Add a repository secret PYPI_API_TOKEN whose value is your token string (same value you would put in TWINE_PASSWORD). Then:

git tag v1.5.1
git push origin v1.5.1

The tag should match the version in fast_cli/__init__.py.

---

Layout

fast.cli/
├── fast_cli/
│   ├── app.py              # CLI entry point
│   ├── bundled/          # git_log_recorder.py (source for setup-commit-log)
│   └── commands/         # Command groups and implementations
├── _maint/scripts/       # Optional copy in other repos (see setup-commit-log)
├── .pre-commit-config.yaml
└── …

For maintainer notes, see _maint/README.md.