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 — Searchable command picker
  • 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

ASCII-art titles (optional)

uv add "usecli[figlet]"
# or: pip install "usecli[figlet]"

The extra installs pyfiglet. With it, usecli init offers a figlet font picker and banners are rendered in the chosen font. Without it, the picker is skipped and banners print as colored text: title and version on one line, description below.

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    # Searchable picker for all commands
usecli -i hello         # Run 'hello' command interactively

The picker opens in-place with vim-style keys: j/k or the arrow keys move, / starts search, and enter runs the highlighted command. esc leaves search mode but keeps the filter active (normal-mode navigation still works); ctrl-u clears the filter. Command names, descriptions, the title and the status bar use your theme colors; the highlighted row switches to the theme's highlight style.

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.2.6

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.2.6
File Size Uploaded Provenance Actions
usecli-0.2.6.tar.gz 111.3 kB Without provenance Details for usecli-0.2.6.tar.gz

Built distribution (wheel)

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

Total release size: 251.7 kB

Release files / usecli-0.2.6.tar.gz

Download URL usecli-0.2.6.tar.gz
Size 111.3 kB
Tags Source
SHA-256 checksum
How to use checksums
ae253d7226b65565bd08431854fc91f1bb378d9883e8e48011211d1b92ef33f4
BLAKE2b-256 checksum
How to use checksums
29dc8fe2f195cbe6673a8f22c6746b9ef043a3ec1f44ad9f62d924320529dbbd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

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

Download URL usecli-0.2.6-py3-none-any.whl
Size 140.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9f6119088aafd5cb97bb48be55b22c2a53b0d9b326185e9553acecb8f738f6e4
BLAKE2b-256 checksum
How to use checksums
2edeea397aa6a0a77900aa00fff437bc71855103eaa2e305e0c5b3fe87c4224f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for usecli 0.2.6

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.2.6 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