FVNever.Todosaurus.Cli 1.11.0

Todosaurus

CLI for Todosaurus — a tool to process TODO issues in a repository.

Installation

Todosaurus CLI is a .NET tool, so it can be installed by getting a .NET SDK 10 or later, and then executing a shell command

$ dotnet tool install --global FVNever.Todosaurus.Cli

for global installation or

$ dotnet new tool-manifest
$ dotnet tool install FVNever.Todosaurus.Cli

for local solution-wide installation.

Usage

After installation, the tool will be available in shell as dotnet todosaurus.

Command-Line Syntax

dotnet todosaurus [global-switches…] [command] [command-switches…]

Global switches:

• --config <path> — path to configuration file (default: todosaurus.toml in working directory);
• --strict — treat warnings as errors; when any warning is emitted during the scan and the scan would otherwise succeed, exit with code 1 instead of 0. Recommended for CI;
• --help | -h | -? — print the help;
• --version — print the program version.

todosaurus files

This is a diagnostic command.

Lists text files in the current directory (recursively) that are eligible for TODO checking. Outputs one relative path per line, sorted alphabetically.

todosaurus scan

This is the default command — it runs when todosaurus is invoked without a subcommand.

Scans all eligible text files (see file discovery below) for unresolved TODO items (see TODO Format Specification) and reports them.

The command exits with a code reflecting the highest-priority issue found, making it suitable for CI enforcement.

When Todosaurus encounters a connected TODO (e.g., TODO[#123]), it can verify the referenced issue against GitHub. If the issue is closed or does not exist, Todosaurus reports a warning.

The output format depends on the environment:

• CI (when the CI environment variable is set, as is standard for GitHub Actions, GitLab CI, Travis CI, Azure Pipelines, and most other CI providers): each finding is printed as a GitHub Actions workflow command ::warning and ::error annotation. This makes unresolved TODOs appear as inline annotations in pull request diffs.
• Local (when CI is not set): each finding is printed in a human-readable format: file(line): text.

Configuration File

Todosaurus reads settings from a TOML configuration file. By default, it looks for todosaurus.toml in the working directory. Use the --config switch to specify a different path.

If --config is not provided and no todosaurus.toml exists, Todosaurus runs with default settings. If --config points to a missing file, the command exits with an error.

Example todosaurus.toml:

exclusions = [
    "build/**",
    "*.generated.cs",
]

[tracker]
url = "https://github.com/owner/repo"

Glob patterns follow the syntax of Microsoft.Extensions.FileSystemGlobbing — * matches within a directory, ** matches across directories.

If tracker.url is not configured, Todosaurus determines the repository automatically:

1. Reads the URL of the origin Git remote (git remote get-url origin).
2. Parses the GitHub owner and repository name from the URL.

If neither source is available and connected TODOs exist, the command exits with code 2.

Environment Variables

CI

Todosaurus reads the CI environment variable to determine if it's running in a CI environment. Certain aspects of behavior depend on it:

1. In the CI environment, GITHUB_WORKSPACE is mandatory.
2. In the CI environment, the output format is changed to GitHub Actions workflow command syntax.
3. In the CI environment, only Git-tracked files are scanned (untracked files are excluded from file discovery). See file discovery for details. This is done to not signal on any CI-only build artifacts that shouldn't be analyzed.

GITHUB_TOKEN, GH_TOKEN: GitHub Authentication

Todosaurus reads a GitHub token from environment variables (checked in order):

1. GITHUB_TOKEN — automatically available in GitHub Actions.
2. GH_TOKEN — used by the GitHub CLI.

Without a token, only public repositories can be checked, subject to GitHub's unauthenticated rate limit of 60 requests per hour.

Locally, you might be interested in using the following script:

$env:GH_TOKEN = gh auth token
todosaurus …

GITHUB_WORKSPACE

When running in the CI environment, Todosaurus will use GITHUB_WORKSPACE to find the path to the repository root.

Exit Codes

When multiple conditions are present, the highest-priority code is returned (priority equals code value: 7 > 0).

GitHub Actions setup

To use Todosaurus with connected TODO checking in a GitHub Actions workflow:

name: TODOs
on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
      - run: dotnet tool install --global FVNever.Todosaurus.Cli
      - name: Check TODOs
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: dotnet todosaurus scan --strict

(You might want to add --version to the dotnet tool install command to specify a particular version and avoid siutations when an incompatible update gets instaled on your CI runner.)

The --strict flag ensures that warnings (such as rate-limit notices or unresolvable tracker URLs) cause the workflow step to fail, rather than silently passing. This is recommended for CI to catch configuration issues early.

The default GITHUB_TOKEN provided by GitHub Actions has read access to the repository's issues, which is sufficient for connected TODO checking. No additional secrets or permissions are required.

File discovery

• Anywhere inside of a Git repository (if a .git folder detected): runs git ls-files to list files for scanning. The set of files depends on the environment:
  • In CI mode (when the CI environment variable is set): only Git-tracked files (files in the index) are scanned. This avoids false positives from generated or cached files that are not tracked by Git and not covered by .gitignore (e.g., package caches restored during CI builds, build artifacts, etc.).
  • Locally (when CI is not set): tracked files and untracked files that are not ignored by .gitignore are both scanned. This means newly created files appear even before they are staged, but files matching .gitignore patterns are excluded.
  • Git executable not found: if the git command is not available on PATH, a warning is printed to stderr and the command falls back to recursive filesystem enumeration.
• Outside of a Git repository: recursively enumerates all the files under the current directory.

Binary file detection

Files are classified as text or binary using a heuristic: the first 8000 bytes of each file are read; if any NUL (0x00) byte is found, the file is considered binary and excluded from the output. Files that cannot be read (permission errors, etc.) are skipped with a warning.

Documentation

• Changelog
• Contributor Guide
• Maintainer Guide

License

The project is distributed under the terms of the MIT license.

The license indication in the project's sources is compliant with the REUSE specification v3.3.