Metadata-Version: 2.4
Name: fastmvc-cli
Version: 1.5.0
Summary: FastMVC CLI — interactive FastAPI project generator and tooling
Project-URL: Homepage, https://github.com/fastmvc/fast.cli
Project-URL: Repository, https://github.com/fastmvc/fast.cli
Author: Shiv
License: MIT
License-File: LICENSE
Keywords: cli,fastapi,fastmvc,generator,mvc
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: fast-dashboards>=1.5.0
Requires-Dist: fast-database>=1.5.0
Requires-Dist: fast-middleware>=1.5.0
Requires-Dist: fast-mvc>=1.4.0
Requires-Dist: fast-platform>=1.5.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: all
Requires-Dist: build>=1.2; extra == 'all'
Requires-Dist: fast-dashboards; extra == 'all'
Requires-Dist: fast-database; extra == 'all'
Requires-Dist: fast-middleware; extra == 'all'
Requires-Dist: fast-mvc[all,dev,docs,interactive]; extra == 'all'
Requires-Dist: fast-platform[all]; extra == 'all'
Requires-Dist: pre-commit>=3.0; extra == 'all'
Requires-Dist: pytest-cov>=4.0; extra == 'all'
Requires-Dist: pytest-mock>=3.0; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: questionary>=2.0; extra == 'all'
Requires-Dist: twine>=5.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: questionary>=2.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: interactive
Requires-Dist: questionary>=2.0; extra == 'interactive'
Description-Content-Type: text/markdown

# 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](#install)
- [Global options](#global-options)
- [Command map](#command-map)
- [Project generation](#project-generation)
- [Scaffolding (`add`)](#scaffolding-add)
- [Environment (`env`)](#environment-env)
- [Database migrations (`db`)](#database-migrations-db)
- [Documentation (`docs`)](#documentation-docs)
- [Caching (`cache`)](#caching-cache)
- [Background tasks (`tasks`)](#background-tasks-tasks)
- [Cleanup (`decimate`)](#cleanup-decimate)
- [Commit history (`setup-commit-log`)](#commit-history-setup-commit-log)
- [Legacy (`make`)](#legacy-make)
- [Related repositories](#related-repositories)
- [Layout](#layout)
- [Publishing to PyPI](#publishing-to-pypi)

---

## Install

```bash
pip install fastmvc-cli
```

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

```bash
pip install "fastmvc-cli[interactive]"
```

For development and tests:

```bash
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:

```bash
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

```bash
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

```bash
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).

```bash
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). |

```bash
fast db migrate -m "Add users table"
```

### `db upgrade`

Apply migrations.

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

```bash
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.

```bash
fast docs generate
```

### `docs deploy`

Runs **`mkdocs gh-deploy`** with an optional commit message.

| Option | Shorthand | Default |
|--------|-----------|---------|
| `--message` | `-m` | `Deploy documentation` |

```bash
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.

```bash
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. |

```bash
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.

```bash
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.). |

```bash
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:

```bash
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](https://github.com/shregar1/fast.mvc) |

This repo’s **`package metadata`** references [github.com/fastmvc/fast.cli](https://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](https://pypi.org/manage/account/token/).

### Local build and upload

Install build tools (included in the **`dev`** extra):

```bash
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):

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

On one line:

```bash
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:

```bash
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`**.
