devx/docs/user/cli-commands.md

# CLI Commands

devx provides a CLI with three command groups: `ci`, `tools`, and `molecule`.
Each subcommand delegates to the corresponding Python module via
`python -m devx.*`, so `devx ci release` is equivalent to
`python -m devx.ci.release`.

```bash
devx --help        # show all command groups
devx --version     # show package version
devx ci --help     # show CI commands
devx tools --help  # show tools commands
devx molecule --help  # show molecule commands
```

## CI Commands

### `devx ci auto-merge`

Auto-merge a PR when all CI checks pass. Reads the task ID from the branch
name, validates the PR title format against
the Vikunja task title, extracts the conventional commit message from PR
commits, and squash-merges with `{PREFIX}-N <conventional commit>` title.

If the head branch is behind master (HTTP 405), automatically pulls master,
rebases, force-pushes, and retries the merge.

```bash
devx ci auto-merge <branch> <pr_title> <owner/repo> <pr_number>
# Example:
devx ci auto-merge DEVX-12-add-feature "DEVX-12: Add feature" oblachno-oss/devx 42
```

### `devx ci check-translations`

Check translation files for gaps, dead keys, and missing languages. Validates
translation files against the Python source code that uses them. By default,
checks `src/devx/translations.json` against `src/devx/**/*.py`.

Checks performed:
- **Missing keys** — a `_()` call in code has no entry in the translations file
- **Dead keys** — a key in the translations file is not used in any code
- **Missing languages** — a key exists but is missing one of the six
  supported languages (en, bg, de, ru, zh, pl)

```bash
devx ci check-translations
devx ci check-translations --translations path/to/translations.json
```

### `devx ci classify-changes`

Classify git changes as user-facing or workflow-only. Used to skip releases
for infrastructure-only changes. Classification rules are configured in
`pyproject.toml` under `[tool.devx.classify]`.

```bash
devx ci classify-changes --base origin/master --head HEAD
devx ci classify-changes --base origin/master --head HEAD --github-output
devx ci classify-changes --quiet --check user-facing
devx ci classify-changes --check ansible  # custom tag from pyproject.toml
```

Options:
- `--base <ref>` — base ref (default: latest tag)
- `--head <ref>` — head ref (default: HEAD)
- `--quiet` — only output true/false
- `--check <category>` — check specific category: `all` (default),
  `user-facing`, or any tag name defined in `[tool.devx.classify.tags]`
- `--github-output` — write results to `$GITHUB_OUTPUT` for CI workflow steps

Exit code 2 indicates workflow-only changes (no release needed).

### `devx ci detect-release-commit`

Detect whether the latest git commit is a release commit
(`release: vX.Y.Z [skip ci]`). Writes `is-release=true` or `is-release=false`
to `$GITHUB_OUTPUT` for use in CI workflow conditionals.

```bash
devx ci detect-release-commit
```

### `devx ci discover-runners`

Discover available Gitea Actions runners for dynamic job distribution.
Queries the Gitea API for registered runners at repository, organization, and
instance (admin) levels. Falls back to `MOLECULE_RUNNERS` repo variable or
`DEFAULT_MAX_RUNNERS` (3).

```bash
devx ci discover-runners --owner oblachno-oss --repo devx
devx ci discover-runners --owner oblachno-oss --repo devx --count
devx ci discover-runners --owner oblachno-oss --repo devx --indices
```

Options:
- `--count` — print the number of available runners
- `--indices` — print a JSON array `[0, 1, ..., N-1]` for use as a dynamic
  matrix in Gitea Actions

### `devx ci distribute-files`

Distribute files across parallel runners (round-robin). Discovers files
matching a glob pattern, sorts them for deterministic ordering, then assigns
them round-robin to `max_runners` groups. The assigned group for
`runner_index` is written to `$GITHUB_ENV`.

```bash
devx ci distribute-files --pattern "tests/integration/test_*.py" \
  --runner-index 1 --max-runners 3 --github-env
```

Options:
- `--pattern <glob>` — glob pattern for files to distribute
- `--runner-index <i>` — current runner index (0-based)
- `--max-runners <n>` — total number of runners (default: 3)
- `--github-env` — write file list to `$GITHUB_ENV`
- `--skip-if-excess` — skip if fewer files than runners

### `devx ci doc-coverage`

Check documentation coverage for CLI commands and major modules. Parses
Click commands from `cli.py` and checks if each has documentation in
`docs/user/cli-commands.md`. Verifies core modules are documented in
`architecture.md` and CI scripts in `ci-cd-workflow.md`.

```bash
devx ci doc-coverage
devx ci doc-coverage --docs-dir docs/ --fail-on-missing
```

Options:
- `--docs-dir <dir>` — path to the docs directory (default: `docs/`)
- `--fail-on-missing` — exit with non-zero status if any documentation is
  missing

### `devx ci integration-guard`

Run pytest with cross-runner failure detection. If any
other integration-tests matrix runner reports failure, the current pytest
subprocess is killed and this runner exits early with code 1.

```bash
devx ci integration-guard -- test_a.py test_b.py
devx ci integration-guard -- -x -v --tb=short test_a.py
```

Environment variables:
- `GITEA_URL` — base URL of the Gitea instance
- `REPO_TOKEN` — API token with repo access
- `RUN_ID` — workflow run ID (`GITHUB_RUN_ID`)
- `JOB_NAME` — base job name (`GITHUB_JOB`)
- `MATRIX_INDEX` — current matrix index (runner-index)
- `GITEA_REPOSITORY` — repository in `owner/repo` format

### `devx ci notify-failure`

Create a Gitea issue when a CI workflow fails. Uses the tea CLI for issue
creation with a `bug` label if available.

```bash
devx ci notify-failure --repo oblachno-oss/devx --run-id 123 \
  --workflow ci --commit abc123def456
devx ci notify-failure --repo oblachno-oss/devx --run-id 123 \
  --workflow post-merge/release --commit abc123def456 --auto-login
```

Options:
- `--repo <owner/repo>` — repository (required)
- `--run-id <id>` — CI run ID (required)
- `--workflow <name>` — workflow name (required)
- `--commit <sha>` — commit SHA (required)
- `--auto-login` — configure tea CLI login from `REPO_TOKEN` before creating
  the issue

### `devx ci post-merge`

Update Vikunja task after a merge to master. Extracts the task ID from the
commit message, marks the task as done, and posts a comment with the merge SHA.

```bash
devx ci post-merge "DEVX-12 feat: add feature" --git-sha abc123def456
```

### `devx ci pr-review`

Run automated PR review. Fetches the PR diff via the Gitea API and runs a
series of checks, posting a structured review (`COMMENT` or
`REQUEST_CHANGES`).

Checks: architecture compliance, best practices, security, i18n, resource
management, documentation, test coverage, and commit conventions.

```bash
devx ci pr-review 42 oblachno-oss/devx
```

### `devx ci publish`

Build package, publish to Gitea PyPI registry (or standard PyPI), and create
a Gitea release with git-cliff-generated notes.

```bash
devx ci publish v1.0.0 oblachno-oss/devx
devx ci publish v1.0.0 oblachno-oss/devx --registry-url https://git.example.com/api/packages/owner/pypi
devx ci publish v1.0.0 oblachno-oss/devx --skip-build  # Gitea release only
```

Options:
- `--registry-url <url>` — Gitea PyPI registry URL. Defaults to
  `DEVX_PYPI_REGISTRY_URL` env var or a URL derived from `GITEA_API_URL`.
  When set, publishes to Gitea PyPI instead of standard PyPI (unless
  `PYPI_TOKEN` is also set).
- `--skip-build` — skip package build and PyPI publish (for non-Python repos
  that only need a Gitea release)

### `devx ci push-badges`

Generate badge SVG files and push them to the `badges` branch. Also updates
`README.md` and `docs/index.md` on master with cache-busting
`raw/commit/<sha>/` URLs.

```bash
devx ci push-badges
devx ci push-badges --output-dir .badges/ --branch master
devx ci push-badges --no-readme-update  # skip README update (local testing)
devx ci push-badges --retries 3  # retry on git push failures
```

Options:
- `--output-dir <dir>` — temporary directory for badge files (default:
  `.badges/`)
- `--branch <branch>` — branch to sync before generating badges (default:
  `master`)
- `--no-readme-update` — skip updating README with cache-busting URLs
- `--retries <n>` — number of attempts on git push failures (default: 1).
  Between attempts, fetches latest master and waits 10s.

### `devx ci release`

Automated release: calculate next version, update files, tag, and push. Uses
git-cliff to determine the next semver version from conventional commits.

```bash
devx ci release
devx ci release --dry-run          # preview without making changes
devx ci release --skip-tests       # skip lint and tests (emergency only)
devx ci release --verify           # check tag/version/changelog alignment
```

Options:
- `--dry-run` — show what would happen without making changes
- `--skip-tests` — skip lint and test verification (NOT recommended — only
  for emergency releases)
- `--verify` — verify tag/version/changelog alignment and exit (no changes
  made)

### `devx ci sync-wiki`

Sync documentation from `docs/` to the Gitea wiki. Reads `docs/mapping.json`
for file-to-page mapping. Pages that exist in the wiki but not in the mapping
are left untouched.

```bash
devx ci sync-wiki --repo oblachno-oss/devx
devx ci sync-wiki --repo oblachno-oss/devx --dry-run
devx ci sync-wiki --repo oblachno-oss/devx --verify
devx ci sync-wiki --repo oblachno-oss/devx --strict
```

Options:
- `--dry-run` — show what would happen without making changes
- `--repo <owner/repo>` — repository (auto-detected if omitted)
- `--verify` — after syncing, verify each page has non-empty content. Exit 1
  if any page is empty or mismatched.
- `--strict` — full integrity check: verify page count, missing pages, stale
  pages, and content. Implies `--verify`.

### `devx ci validate-commit-msg`

Validate commit messages for conventional commit format. On feature branches:
conventional commits only (no `{PREFIX}-N` prefix). On master: must have
`{PREFIX}-N` prefix from auto-merge, followed by a conventional commit
message.

```bash
devx ci validate-commit-msg commit-msg.txt
devx ci validate-commit-msg commit-msg.txt --branch master
```

Options:
- `--branch <branch>` — override branch detection (for CI use)

## Tools Commands

### `devx tools check-test-speed`

Run unit tests and enforce execution-time budgets. Two quality gates:

- **Total suite time** must not exceed `--max-seconds` (default: 10s)
- **Per-test time** — no individual test may exceed `--max-single-seconds`
  (default: 0.5s, 0 to disable)

Runs `make test-unit` with `PYTEST_ADDOPTS=--durations=0` so pytest emits
per-test timing lines.

```bash
devx tools check-test-speed
devx tools check-test-speed --max-seconds 10
devx tools check-test-speed --max-seconds 4 --max-single-seconds 0.5
```

### `devx tools configure-repo`

Configure repository: branch protection and labels via the Gitea REST API.
Sets up master branch protection (required status checks, block on rejected
reviews, block on outdated branch) and creates standard labels.

```bash
devx tools configure-repo --repo devx --owner oblachno-oss
```

Status check contexts are read from `DEVX_STATUS_CHECKS` (comma-separated) or
default to `CI / quality (pull_request)`.

### `devx tools generate-badges`

Generate self-contained SVG badge files from project metrics. Runs
pytest-cov, doc-coverage, lint checks, and version extraction, then writes
SVG files that can be served as static files from the Gitea raw file API.

Badges generated: `coverage.svg`, `tests.svg`, `docs.svg`, `quality.svg`,
`version.svg`, `python.svg`.

```bash
devx tools generate-badges
devx tools generate-badges --output-dir .badges/
```

### `devx tools generate-cliff-config`

Generate a `cliff.toml` configuration file with the correct task ID prefix
preprocessor. Eliminates the need to manually duplicate and maintain
`cliff.toml` across repos that use devx.

```bash
devx tools generate-cliff-config --prefix GRM
devx tools generate-cliff-config --prefix GRM --output cliff.toml
devx tools generate-cliff-config --prefix GRM --force  # overwrite existing
```

Options:
- `--prefix <prefix>` — task ID prefix (default: `DEVX_TASK_PREFIX` env var
  or `DEVX`)
- `--output <file>` — output file path (default: `cliff.toml`)
- `--force` — overwrite existing file

### `devx tools install-checkmake`

Install checkmake (Makefile linter) if not already present. Tries
`go install` first if Go is available, otherwise downloads the latest
pre-built Linux binary from the official GitHub releases.

```bash
devx tools install-checkmake
```

### `devx tools install-tools`

Install CI/CD development tools that are not Python packages: actionlint,
git-cliff, act_runner, and tea. Each tool is installed to `~/.local/bin` if
not already on PATH. Idempotent: skips tools that are already available.

```bash
devx tools install-tools                    # install all
devx tools install-tools --tool actionlint  # install one
devx tools install-tools --tool git-cliff --tool tea  # install specific
devx tools install-tools --list             # list status
```

### `devx tools setup`

Project setup: install Python dependencies (editable mode with extras),
Ansible Galaxy collections (if `ansible/requirements.yml` exists), pre-commit
hooks (pre-commit, commit-msg, pre-push), and configure the tea CLI login
profile from `.env`.

```bash
devx tools setup --bin .venv/bin
devx tools setup --bin .venv/bin --extras "ci,lint"
devx tools setup --bin .venv/bin --no-pre-commit --no-tea-login
```

Options:
- `--bin <dir>` — virtualenv bin directory (required)
- `--extras <groups>` — pip extras to install (default: `dev`)
- `--no-pre-commit` — skip pre-commit hook installation
- `--no-tea-login` — skip tea CLI login configuration

## Molecule Commands

Molecule commands require the `molecule` extra (`pip install devx[molecule]`).

### `devx molecule all`

Run all molecule scenarios on all supported OS platforms. Sequential
execution — CI uses the parallel matrix instead.

```bash
devx molecule all
devx molecule all --bin .venv/bin
```

### `devx molecule discover-runners`

Discover available Gitea Actions runners for molecule tests. Same logic as
`devx ci discover-runners` but intended for molecule-specific workflows.

```bash
devx molecule discover-runners --owner oblachno-oss --repo devx --indices
```

### `devx molecule distribute`

Distribute molecule (scenario, platform) pairs across N parallel runners.
Discovers scenarios under `ansible/roles/*/molecule/` and crosses them with
the supported OS platform matrix.

```bash
devx molecule distribute --runner-index 1 --max-runners 3
devx molecule distribute --list              # list all scenarios
devx molecule distribute --list-platforms    # list platforms
devx molecule distribute --roles-root ansible/roles  # multi-role repos
```

Options:
- `--runner-index <i>` — current runner index (0-based)
- `--max-runners <n>` — total number of runners (default: 3)
- `--list` — list all scenarios, one per line
- `--list-platforms` — list all platforms, one per line
- `--roles-root <dir>` — roles root directory for multi-role repos (default:
  `ansible/roles`)

### `devx molecule guard`

Run molecule tests sequentially with CI failure polling. A background thread
polls the Gitea API. If any other molecule matrix runner reports failure, the
current molecule subprocess is killed and this runner exits early with code 1.

```bash
devx molecule guard pair1 pair2 pair3
devx molecule guard --roles-root ansible/roles pair1 pair2
```

Each pair is encoded as:
- **Single-role (4-part):** `scenario|platform_name|platform_image|platform_command`
- **Multi-role (5-part):** `role|scenario|platform_name|platform_image|platform_command`

Options:
- `--roles-root <dir>` — roles root directory for multi-role repos

Environment variables:
- `GITEA_URL` — base URL of the Gitea instance
- `REPO_TOKEN` — API token with repo access
- `RUN_ID` — workflow run ID (`GITHUB_RUN_ID`)
- `JOB_NAME` — base job name (`GITHUB_JOB`)
- `MATRIX_INDEX` — current matrix index (runner-index)
- `GITEA_REPOSITORY` — repository in `owner/repo` format