Bijux CLI¶

A modern, predictable CLI framework for Python — strict global flag precedence, first-class plugins, a DI kernel, and an interactive REPL. Build robust, extensible command-line tools that are easy to test, maintain, and scale.

At a glance: Plugin-driven • deterministic flags • DI for testability • REPL • structured JSON/YAML
Quality: 2,600+ tests across layers with 98%+ coverage (see Test Artifacts and HTML coverage). Multi-version CI. Docs build enforced. No telemetry.

Table of Contents¶

Why Bijux CLI?
Try It in 20 Seconds
Key Features
Installation
Quick Start
Plugins in 60 Seconds
Structured Output
Developer Introspection
Global Flags: Strict Precedence
Built-in Commands
When to Use (and Not Use)
Shell Completion
Configuration & Paths
Tests & Quality
Project Tree
Roadmap
Docs & Resources
Contributing
Acknowledgments
License

Back to top

Why Bijux CLI?¶

Click and Typer excel at simple tools. Bijux emphasizes predictability and modularity for complex ones:

Deterministic flags for reliable CI/scripting.
Dependency Injection kernel for testable, decoupled services.
First-class plugins to extend without touching the core.
Interactive REPL for exploration and debugging.

Back to top

Try It in 20 Seconds¶

pipx install bijux-cli  # Or: pip install bijux-cli
bijux --version
bijux doctor
bijux status -f json --no-pretty

Back to top

Key Features¶

Plugin-Driven Extensibility — Scaffold, install, validate; plugins become top-level commands.
Deterministic Behavior ⚖ — Strict flag precedence (see ADR-0002).
DI Kernel — Decouple internals; inspect graphs for debugging/tests.
REPL Shell — Persistent session with history; great for exploration/demos.
Structured Output — JSON/YAML (+ pretty/compact, verbosity, consistent errors).
Diagnostics — Built-in doctor, audit, docs for workflows.
Shell Completion — Bash, Zsh, Fish, PowerShell support.

Back to top

Installation¶

Requires Python 3.11+.

# Isolated install (recommended)
pipx install bijux-cli

# Standard
pip install bijux-cli

Upgrade: pipx upgrade bijux-cli or pip install --upgrade bijux-cli.

Back to top

Quick Start¶

# Discover commands/flags
bijux --help

# Health check
bijux doctor

# REPL mode
bijux
bijux> help
bijux> status
bijux> exit

Back to top

Plugins in 60 Seconds¶

# Scaffold from a real template (local dir or Git URL), then install
# Option A: local template (example uses repo's cookiecutter template)
bijux plugins scaffold my_plugin --template ./plugin_template --force

# Option B: cookiecutter-compatible Git URL
# bijux plugins scaffold my_plugin --template https://github.com/bijux/bijux-plugin-template.git --force

# Install & explore
bijux plugins install ./my_plugin --force
bijux plugins list
bijux my_plugin --help

# Validate & remove
bijux plugins check my_plugin
bijux plugins uninstall my_plugin

Plugins dynamically add top-level commands.

Back to top

Structured Output¶

For automation:

# Compact JSON
bijux status -f json --no-pretty | jq

# Pretty YAML
bijux status -f yaml --pretty

Back to top

Developer Introspection¶

# DI graph
bijux dev di -f json

# Loaded plugins
bijux dev list-plugins

Back to top

Global Flags: Strict Precedence¶

Fixed ordering eliminates ambiguity.

Priority	Flag	Effect
1	`-h`, `--help`	Immediate exit (code 0) with usage; ignores all.
2	`-q`, `--quiet`	Suppress stdout/stderr; preserves exit code.
3	`-d`, `--debug`	Full diagnostics; implies `--verbose`, forces `--pretty`.
4	`-f`, `--format <json\\|yaml>`	Structured output; invalid → code 2.
5	`--pretty` / `--no-pretty`	Indentation toggle (default: `--pretty`).
6	`-v`, `--verbose`	Runtime metadata; implied by `--debug`.

Rationale: ADR-0002

Back to top

Built-in Commands¶

Command	Description	Example
`doctor`	Environment diagnostics	`bijux doctor`
`status`	CLI snapshot	`bijux status -f json`
`repl`	Interactive shell	`bijux repl`
`plugins`	Manage plugins	`bijux plugins list`
`config`	Key-value settings	`bijux config set core_timeout=5`
`history`	REPL history	`bijux history --limit 10`
`audit`	Security checks	`bijux audit --dry-run`
`docs`	Generate specs/docs	`bijux docs --out spec.json`
`dev`	Introspection (DI, plugins)	`bijux dev di`
`sleep`	Pause	`bijux sleep -s 5`
`version`	Version info	`bijux version`

Back to top

When to Use (and Not Use)¶

Use if you need:

Plugins for extensibility.
Deterministic flags for CI/scripts. ADR-0002
REPL for interactive workflows.
DI for modular, testable design.

Overkill if:

You’re building a tiny one-off script (Click/Typer may be simpler).
You don’t need plugins/DI.

Back to top

Shell Completion¶

# Install (writes to your shell’s completion dir)
bijux --install-completion

# Or print the script for manual setup
bijux --show-completion

Zsh tip: Ensure compinit runs and your fpath includes the completion directory.

Back to top

Configuration & Paths¶

Precedence: flags > env > config > defaults.

Config: ~/.bijux/.env (BIJUXCLI_CONFIG)
History: ~/.bijux/.history (BIJUXCLI_HISTORY_FILE)
Plugins: ~/.bijux/.plugins (BIJUXCLI_PLUGINS_DIR)

Example:

export BIJUXCLI_PLUGINS_DIR=./custom-plugins

Back to top

Tests & Quality¶

Depth: 2,600+ tests across unit, integration, functional, and E2E layers.
Coverage: 98%+ code coverage (measured via pytest-cov in CI).
Determinism: CI runs the full suite on multiple Python versions (3.11+).
Artifacts: JSON/YAML fixtures validate structured outputs; E2E simulates real usage (REPL, plugins, DI).
Docs: Read the full testing guide → TESTS.md.

Quick commands:

make test         # all tests
make test-unit    # unit tests only
make test-e2e     # end-to-end tests only

Artifacts: Test Artifacts · JUnit report · HTML coverage report

Back to top

Project Tree¶

A guided map of the repository (what lives where, and why). See PROJECT_TREE.md for the full breakdown.

Quick glance:

api/            # OpenAPI schemas
config/         # Lint/type/security configs
docs/           # MkDocs site (Material)
makefiles/      # Task modules (docs, test, lint, etc.)
plugin_template/# Cookiecutter-ready plugin scaffold
scripts/        # Helper scripts (hooks, docs generation)
src/bijux_cli/  # CLI + library implementation
tests/          # unit / integration / functional / e2e

Back to top

Roadmap¶

v0.2 — Async command support, richer plugin registry.
v1.0 — Community plugin marketplace, benchmarks vs. alternatives.

Track progress and suggest features via Issues.

Back to top

Docs & Resources¶

Site: https://bijux.github.io/bijux-cli/
Changelog: https://github.com/bijux/bijux-cli/blob/main/CHANGELOG.md
Repository: https://github.com/bijux/bijux-cli
Issues: https://github.com/bijux/bijux-cli/issues
Security (private reports): https://github.com/bijux/bijux-cli/security/advisories/new
Tests: TESTS.md
Project Tree: PROJECT_TREE.md
Artifacts: Browse all reports & logs — index · Tests · Lint · Quality · Security · SBOM · API · Citation

When filing issues, include --debug output where possible.

Back to top

Contributing¶

Welcome! See CONTRIBUTING.md for setup, style, and tests. We label good first issue to help you get started.

Bijux CLI¶

Table of Contents¶

Why Bijux CLI?¶

Try It in 20 Seconds¶

Key Features¶

Installation¶

Quick Start¶

Plugins in 60 Seconds¶

Structured Output¶

Developer Introspection¶

Global Flags: Strict Precedence¶

Built-in Commands¶

When to Use (and Not Use)¶

Shell Completion¶

Configuration & Paths¶

Tests & Quality¶

Project Tree¶

Roadmap¶

Docs & Resources¶

Contributing¶

Acknowledgments¶

License¶