Skip to main content

Table of Contents
  1. About
  2. Quick Start
  3. Usage
  4. Entry Points & Packaging
  5. Development
  6. Contributing
  7. License

About

useCli A powerful Python CLI framework for building beautiful, developer-friendly command-line tools. It gives you:

  • Prefix matching — Type he instead of help
  • Interactive mode — Fuzzy finder for commands
  • Auto-generated help — Clean, styled output
  • Command scaffolding — make:command generates boilerplate
  • UI components — Prompts, menus, styled console output

(back to top)

Quick Start

uv add usecli

Install with pip (alternative)

pip install usecli

Initialize

usecli init

Create a command

usecli make:command hello

Your new command is ready in the commands directory:

class HelloCommand(BaseCommand):
    def signature(self) -> str:
        return "hello"

    def description(self) -> str:
        return "Say hello"

    def handle(self, name: str = Argument(..., help="Your name")) -> None:
        console.print(f"Hello, {name}!")

Run it:

usecli hello world

(back to top)

Usage

Prefix Matching

Type partial command names:

usecli he          # help
usecli ma:co       # make:command

Interactive Mode

usecli --interactive    # Fuzzy finder for all commands
usecli -i hello         # Run 'hello' command interactively

Command Groups

Colon-separated commands group automatically in help:

def signature(self) -> str:
    return "db:migrate"

Displays as:

db:
  migrate    Run migrations
  backup     Backup database

Space-separated signatures create nested subcommands:

def signature(self) -> str:
    return "spec show"  # usecli spec show

JSON Output

Every command inherits --json; commands do not declare the option themselves. The flag works before or after a command name:

usecli --json about
usecli about --json

A successful invocation writes exactly one JSON document to stdout:

{"ok":true,"data":null}

A command can return any JSON-serializable value to populate data:

class StatusCommand(BaseCommand):
    def signature(self) -> str:
        return "status"

    def description(self) -> str:
        return "Show service status"

    def handle(self):
        return {"status": "ready", "workers": 3}

Failures preserve a non-zero exit status and use a stable error envelope:

{"ok":false,"error":{"type":"UsageError","message":"No such command","code":2}}

In JSON mode, stdout is reserved for that document. Human-facing output, including console.print() and ordinary print(), is routed to stderr. Prompts and confirmations resolve their declared defaults without reading stdin. A prompt without a default, menus, and --interactive fail immediately with a structured NonInteractiveError instead of blocking.

The existing fields ok, data, error, error.type, error.message, and error.code keep their names and types across compatible releases. New fields may be added.

UI Components

from usecli import Confirm, Menu, Prompt, console

console.print("[green]Done![/green]")
name = Prompt.ask("Enter name")
ok = Confirm.ask("Continue?")
choice = Menu.select(["A", "B", "C"])

Progress Indicators

Use Spinner when the amount of work is unknown and ProgressBar when a total is known:

from usecli import ProgressBar, Spinner

with Spinner("Loading records") as spinner:
    load_records()
    spinner.update("Indexing records")

with ProgressBar(total=len(items), description="Processing") as progress:
    for item in items:
        process(item)
        progress.advance()

Progress always renders to stderr, uses the active usecli theme, and is suppressed automatically in JSON mode, with quiet=True, or when stderr is not attached to a terminal. Calling commands do not need to detect these conditions.

Available Commands

about        Show app info
help         Show help
init         Initialize usecli (usecli only)
inspire      Random quote
upgrade      Upgrade the application to the latest version
make:command Create new command (usecli only)
make:theme   Create new theme (usecli only)
make:bundle  Build a standalone executable with PyInstaller (usecli only)

Upgrades

Every CLI built on usecli ships upgrade, which detects how the running package was installed and delegates to the same package manager — uv tool, pipx, or pip — instead of creating a second installation:

mycli upgrade --check   # show installed/latest versions and the source
mycli upgrade           # confirm and install the latest release
mycli upgrade --force   # skip the prompt and the up-to-date check

The source comes from packaging metadata: PyPI for index installs, and the Git remote for PEP 610 direct_url.json installs. Override it in usecli.config.toml when metadata is not enough (private mirrors, missing direct_url.json, a package name that differs from the command name):

[usecli.upgrade]
enabled = true
source = "git"                                  # "auto" (default) | "pypi" | "git"
package = "mycli"                               # optional
url = "https://github.com/owner/mycli.git"      # required for "git" unless detected
ref = "main"                                    # branch, tag, or commit

Frozen bundles, editable installs, and commit-pinned installs are reported as non-upgradeable with an explanation and manual next step.

(back to top)

Entry Points & Packaging

A usecli CLI can be exposed in several ways, depending on how you distribute and run it. There are three common setups — none requires anything but the base usecli install, and the optional bundler adds PyInstaller packaging on top.

1. Default — console script (no entry point)

The simplest setup. Declare a console script in your project's pyproject.toml:

[project.scripts]
mycli = "usecli:main"

usecli resolves your project's config automatically from the current directory (config discovery), so no main.py is required. Install and run it:

uv add usecli
uv run mycli --help

This is the default — no entry point file of your own is needed.

2. Custom entry point — main.py

If you want your own entry point, use the public runtime API. It works in both development and frozen bundles, and accepts an optional config path (the config file is always named usecli.config.toml):

# main.py
from usecli import run


def main():
    run()  # auto-detect project config
    # run("path/to/usecli.config.toml")          # or point at a specific config


if __name__ == "__main__":
    main()

Run it in development (no PyInstaller required):

uv run python main.py --help

To expose the same entry point as a console script, point [project.scripts] at the main function in your myapp package (the usual src/myapp layout):

[project.scripts]
myapp = "myapp:main"

Because run() injects the located config explicitly, a custom main.py works regardless of whether your CLI also has a [project.scripts] entry.

3. Bundler — standalone executable (optional, requires PyInstaller)

The bundler is an optional feature gated on PyInstaller being installed. Install it with:

uv add "usecli[pyinstaller]"

Once installed, a make:bundle command appears (usecli only) that builds your project into a standalone executable. It asks which mode to use via an interactive menu, and confirms before building (defaults to no unless -y):

uv run usecli make:bundle                  # menu: one file vs one folder + confirm
uv run usecli make:bundle --mode onefile   # single-file executable
uv run usecli make:bundle --mode onedir    # one-folder bundle
uv run usecli make:bundle -y               # skip the confirmation
uv run usecli make:bundle --mode onedir -y # fully programmatic
uv run usecli make:bundle --mode onedir --zip -y  # one-folder bundle + zip

When building a one-folder bundle, make:bundle asks whether to also zip the folder into dist/<name>.zip (PyInstaller's recommended distribution format for one-folder mode). Pass --zip / --no-zip to skip the prompt and force a choice; with -y and no flag, zipping is skipped.

A usecli-bundle console script wraps the same build, and you can drive it from Python too:

uv run usecli-bundle
uv run usecli-bundle --mode onedir
uv run usecli-bundle --mode onedir --zip
from usecli import pyinstaller

pyinstaller()  # auto-detect config, single-file
pyinstaller(mode="onedir")  # one-folder bundle
pyinstaller(mode="onedir", zip=True)  # one-folder bundle + zip
pyinstaller("path/to/usecli.config.toml")  # or point at a specific config

Output lands in dist/ — dist/mycli for onefile, or a dist/mycli/ folder containing the executable (plus _internal/ with the bundled assets) for onedir. With zip=True, a dist/mycli.zip archive is created alongside the folder. make:bundle and usecli-bundle are only available when PyInstaller is installed.

(back to top)

Development

See the Development Guide for setup, testing, and architecture details.

(back to top)

Contributing

Read the Contributing Guide.

Quick workflow:

  1. Fork and branch: git checkout -b feature/name
  2. Make changes
  3. Run checks: uv run poe clean-full
  4. Commit and push
  5. Open a Pull Request

(back to top)

License

MIT. See LICENSE.

(back to top)


Built by thememium

Metadata

Release files for usecli 0.1.80

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for usecli 0.1.80
File Size Uploaded Provenance Actions
usecli-0.1.80.tar.gz 98.8 kB Without provenance Details for usecli-0.1.80.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for usecli 0.1.80
File Interpreter ABI Platform Actions
usecli-0.1.80-py3-none-any.whl Python 3 none any Details for usecli-0.1.80-py3-none-any.whl

Total release size: 226.0 kB

Release files / usecli-0.1.80.tar.gz

Download URL usecli-0.1.80.tar.gz
Size 98.8 kB
Tags Source
SHA-256 checksum
How to use checksums
78c366df1ae1a0afb2a1cf0af190e8100991de99387ac66733be5069b0e40048
BLAKE2b-256 checksum
How to use checksums
d4fe9da4760e02c71b5794d8ae212c4ef1c079eee5739ec6975e2992db19b75d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / usecli-0.1.80-py3-none-any.whl

Download URL usecli-0.1.80-py3-none-any.whl
Size 127.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
be3a0eaadaf888dff171d57aa666503c18a982c17583717cf94db9277a7355e5
BLAKE2b-256 checksum
How to use checksums
09ce503aff8b7cca0cfda221aa2712636a66a08c610f80dcc22bab84fe7fc3c0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for usecli 0.1.80

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.80 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page