bijux-cli 0.2.0

Lean, plug-in-driven CLI kernel

Bijux CLI

Bijux CLI is a framework for building long-lived, complex command-line tools in Python.

It is designed for CLIs that grow, accumulate features, gain plugins, and must remain predictable, testable, and understandable years after their first release.

Bijux is not a wrapper around argument parsing. It is an execution framework for serious tools.

Bijux is built for engineers who care about:

• deterministic global flags (no ambiguity, no surprises),
• first-class plugins with explicit lifecycles,
• a real dependency-injection kernel,
• structured output for automation,
• a unified synchronous and asynchronous execution model,
• and an interactive REPL for exploration and debugging.

If you have ever watched a CLI become fragile as it scaled, Bijux exists to prevent that.

At a glance Plugin-driven · Deterministic flags · Dependency Injection · Sync + Async · REPL · JSON/YAML output Quality 1,800+ tests across all layers · 98%+ coverage · Multi-Python CI → See Test Artifacts and HTML coverage

---

Table of Contents

• Why Bijux CLI?
• How to Think About Bijux
• Try It in 20 Seconds
• Key Features
• Installation
• Platform Support
• Quick Start
• Plugins in 60 Seconds
• Plugin Non-Goals
• 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
• Stability Notes
• Roadmap
• Docs & Resources
• Contributing
• Acknowledgments
• License

---

Why Bijux CLI?

Click and Typer are excellent for small or simple tools.

Bijux is for complex CLIs where:

• global flags must behave consistently in CI and automation,
• commands may be synchronous or asynchronous,
• features and plugins are added incrementally,
• internal state must be observable and testable,
• and regressions must be caught early.

Bijux deliberately trades a small amount of upfront structure for long-term clarity and stability.

---

How to Think About Bijux

A Bijux command flows through a fixed, explicit pipeline:

intent → policy resolution → (sync | async) execution → emission → exit

Key principles:

• Flags never compete — precedence is strict and deterministic.
• Decisions are made once, early in execution.
• Services are injected, never hidden behind globals.
• Commands do not format output — emission is centralized.
• Async and sync commands share the same semantics.
• The REPL uses the exact same execution path as the CLI.

If you reason about Bijux in these terms, the framework becomes predictable rather than magical.

---

Try It in 20 Seconds

pipx install bijux-cli   # or: pip install bijux-cli

bijux --version
bijux doctor
bijux status -f json --no-pretty

---

Key Features

Deterministic Global Flags

Global flags follow strict precedence, eliminating ambiguity and unexpected behavior in scripts and CI pipelines.

Unified Sync + Async Execution

Commands may be implemented as synchronous or async functions. Bijux runs both through the same execution pipeline, guaranteeing identical behavior for:

• flag precedence,
• output formatting,
• logging,
• and exit codes.

Async support is part of the core runtime — not a bolt-on.

Dependency Injection (DI)

All services are explicit and injectable:

• no hidden globals,
• easy mocking,
• inspectable dependency graphs.

First-Class Plugins

Plugins are treated as real system components:

• scaffolded from templates,
• validated before loading,
• dynamically exposed as top-level commands.

Interactive REPL

Explore and debug using a persistent shell:

• identical semantics to CLI execution,
• history and introspection built in.

Structured Output

Every command can emit:

• JSON or YAML,
• pretty or compact,
• consistent error envelopes suitable for automation.

Built-in Diagnostics

Commands like doctor, audit, and docs help verify environments and workflows.

---

Installation

Requires Python ≥ 3.11 (3.11–3.13 tested).

# Recommended (isolated)
pipx install bijux-cli

# Standard
pip install bijux-cli

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

---

Platform Support

• Supported: Linux, macOS r* Not supported: Windows

Bijux relies on POSIX filesystem and process semantics.

---

Quick Start

bijux --help
bijux doctor

# Enter REPL
bijux
bijux> help
bijux> status
bijux> exit

---

Plugins in 60 Seconds

# Scaffold a plugin
bijux plugins scaffold my_plugin --template ./plugin_template --force

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

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

Plugins dynamically add top-level commands without modifying the core.

---

Plugin Non-Goals

Bijux plugins are not sandboxed.

There are:

• no security guarantees,
• no isolation,
• no permission model.

Only install plugins you trust.

---

Structured Output

For automation and scripting:

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

# Pretty YAML
bijux status -f yaml --pretty

---

Developer Introspection

# Inspect the DI graph
bijux dev di -f json

# List loaded plugins
bijux dev list-plugins

---

Global Flags & Strict Precedence

Flags short-circuit in a fixed order. Once a higher-priority flag applies, lower-priority inputs are ignored.

Priority	Flag	Effect
1	-h, --help	Immediate exit with usage
2	-q, --quiet	Suppress stdout/stderr
3	--log-level debug	Full diagnostics; forces pretty output
4	-f, --format json / yaml	Structured output
5	--pretty / --no-pretty	Formatting toggle
6	--log-level <level>	Logging threshold

See the full rationale in the Precedence docs.

---

Built-in Commands

Command	Purpose
doctor	Environment diagnostics
status	CLI snapshot
repl	Interactive shell
plugins	Manage plugins
config	Key-value settings
history	REPL history
audit	Security checks
docs	Generate specs/docs
dev	Introspection tools
sleep	Pause execution
version	Version info

---

When to Use (and Not Use)

Use Bijux if you need:

• extensibility via plugins,
• deterministic behavior in CI,
• sync + async commands under one model,
• structured output,
• testable internals.

It may be overkill if:

• you are writing a one-off script,
• your CLI will never grow,
• plugins and DI provide no value.

---

Shell Completion

bijux --install-completion
bijux --show-completion

Supports Bash, Zsh, Fish, and PowerShell.

---

Configuration & Paths

Precedence: flags → env → config → defaults

Purpose	Path	Env
Config	~/.bijux/.env	BIJUXCLI_CONFIG
History	~/.bijux/.history	BIJUXCLI_HISTORY_FILE
Plugins	~/.bijux/.plugins	BIJUXCLI_PLUGINS_DIR

---

Tests & Quality

Bijux is tested to protect users from regressions, not to discourage contribution.

• 1,800+ tests across unit, integration, functional, E2E, and nightly layers
• 98%+ coverage enforced in CI
• Property-based and stateful tests
• Benchmarks with thresholds

Run locally:

make test
make test-unit
make test-night

Artifacts: https://bijux.github.io/bijux-cli/artifacts/

---

Project Tree

api/            OpenAPI schemas
config/         Lint/type/security configs
docs/           Documentation (MkDocs)
makefiles/      Task modules
plugin_template/Plugin scaffold
scripts/        Helper scripts
src/bijux_cli/  Core implementation
tests/          All test layers

---

Stability Notes

• Core CLI semantics (flags, precedence, exit behavior) are stable.
• The async execution model is stable and supported.
• Plugin metadata and loader internals may evolve before v1.0.
• Breaking changes, when unavoidable, will be documented clearly.

---

Roadmap

• v0.3 — Plugin ergonomics improvements, async-first examples, registry tooling.
• v1.0 — Plugin compatibility guarantees, long-term stability contract.

---

Docs & Resources

• Documentation: https://bijux.github.io/bijux-cli/
• Artifacts: https://bijux.github.io/bijux-cli/artifacts/
• Repository: https://github.com/bijux/bijux-cli

---

Contributing

Contributions are welcome. See CONTRIBUTING.md.

---

Acknowledgments

Built on Typer, FastAPI, and Injector.
Inspired by Click, Typer, and Cobra.

---

License

Apache-2.0. © 2025 Bijan Mousavi.

Changelog

All notable changes to Bijux CLI are documented here. This project adheres to Semantic Versioning and the Keep a Changelog format.

---

0.2.0 – 2026-01-26

Added

• Linear bootstrap flow with explicit phase boundaries and a first-class CLIIntent
• Rebuilt E2E suite with domain taxonomy, invariants, and a subprocess harness
• Nightly fuzz and stress suites under tests/nightly with dedicated markers
• Expanded regression coverage for bootstrap paths, flags matrix, plugin loader/metadata, and real serializer roundtrips
• Benchmarks with thresholds for startup, discovery (cold/warm), config load, REPL, and help/version fast paths
• API contract gating with stricter schema validation and schemathesis checks
• Docs rebuilt into concepts/guides/reference/examples with section indexes
• API purity guard enabled in CI to prevent IO in API calls

Changed

• Centralized CLI policy resolution for routing, exit intent, and precedence
• Infra strictness: explicit formats/targets required; no guessing
• Plugin lifecycle contract with explicit states and early metadata validation
• Test organization aligned to src/ with merged regression suite and nightly rename
• MkDocs generator and nav rebuilt to match the new docs tree

Fixed

• Help output routing for structured formats
• Exit-policy invariants to detect real Python tracebacks only
• API validation error payloads now JSON-encoded with stable schema

Removed

• Legacy root docs pages and ADR directory (decisions moved into canonical docs)
• Thin CLI core wrappers (emit/validation) consolidated

Back to top

0.1.3 – 2025-08-20

Added

• ADR-0005: Zero-root-pollution via Makefile-orchestrated artifact containment (all generated outputs under artifacts/).
• Curated release assets: zipped bundles for tests (py311/py312/py313) and for lint, quality, security, api, docs, sbom, citation, build, plus consolidated checksums.
• End-to-end automation: GitHub Actions to publish to PyPI, create a GitHub Release with curated bundles, and deploy docs.

Changed

• Makefiles + workflows brought into full ADR-0005 compliance: CI uploads/downloads only artifacts/**; docs deploy hydrates from CI artifacts and builds from artifacts/docs/**.

Back to top

---

0.1.2 – 2025-08-17

Added

• New Documentation Engine: Introduced a new modular documentation builder in scripts/docs_builder/ that replaces the previous helper script.
• CI Artifact Pages: The documentation site now automatically generates detailed pages for all CI artifacts, including tests, linting, code quality, security, API tests, SBOMs, and citation files.
• Release Evidence: The publish workflow now downloads all artifacts from the CI run, packages them as evidence/*.tar.gz bundles, and attaches them to the GitHub Release for traceability.
• Build Hygiene: Makefiles now enforce a "hygienic" build process, ensuring all temporary files, caches, and build outputs are stored under the artifacts/ directory to prevent root directory pollution.

Changed

• CI/CD Overhaul:
  • The ci.yml workflow now uploads each category of artifact separately for better organization and downstream consumption.
  • The docs.yml workflow now waits for the main CI run to complete, downloads all artifacts, and uses them to build a data-rich documentation site.
  • The publish.yml workflow has been streamlined and made more robust, removing the optional "wait for docs" step and improving tag detection.
• Documentation Content: All top-level Markdown documents (README.md, USAGE.md, TESTS.md, TOOLING.md, CONTRIBUTING.md, etc.) have been significantly rewritten and expanded with tables of contents, back-to-top links, and cross-references to the new artifact pages.
• Build System:
  • All Makefile modules have been refactored to use the new hygienic artifacts/ directory structure for outputs and caches.
  • tox.ini has been updated to align with the new Makefile targets and to run a comprehensive suite of checks for the py311 environment, mirroring the full CI validation process.
• API Schema: The OpenAPI schema.yaml has been improved with stricter validation (additionalProperties: false), better descriptions, response links, and more detailed examples.
• Source Code: Refactored async handling in src/bijux_cli/api.py and improved type safety across multiple modules with clearer casts.

Fixed

• Type Safety: Resolved numerous previously ignored type errors throughout the codebase and test suite.
• API Endpoint Logic: Corrected the item update logic in src/bijux_cli/httpapi.py by removing a faulty check for duplicate names that was causing incorrect 409 Conflict errors.
• Test Suite: Improved the stability and correctness of E2E tests by enhancing golden file comparisons and fixing brittle assertions.

Back to top

---

0.1.1 – 2025-08-14

Added

• Publish pipeline: GitHub Actions publish.yml that publishes via make publish only after required checks are green and a tag is present.
• Project map: PROJECT_TREE.md (and docs/project_tree.md) with a curated overview.
• Developer Tooling page: TOOLING.md (and docs/tooling.md) with embedded configs, Makefile snippets, and CI workflows via include-markdown.
• Docs assets: Community landing page, Plausible analytics partial, and CSS overrides.

Changed

• Docs generator (scripts/docs_builder/mkdocs_manager.py):
  • Copies README, USAGE, TESTS, PROJECT_TREE, and TOOLING into the site with link rewrites and {#top} anchors.
  • Generates mkdocstrings pages for all modules under src/bijux_cli/**.
  • Builds one consolidated API Reference with this structure:
    • top: Api Module, Cli Module, Httpapi Module
    • sections (collapsed by default): Commands, Contracts, Core, Infra, Services
    • nested groups for command subpackages (config/, dev/, history/, memory/, plugins/) beneath Commands.
  • Emits reference/**/index.md to power Material’s section indexes.
• MkDocs config (mkdocs.yml): tightened plugin ordering and settings for include-markdown, enabled section indexes, and strict mode; added watch paths for configs and scripts.
• README / USAGE: Refined copy; standardized top anchors and links to TESTS.md/PROJECT_TREE.md/TOOLING.md.
• SECURITY.md: Rewritten with clearer reporting, SLAs, scope, and safe harbor.
• Makefiles: macOS-safe env handling; Cairo-less Interrogate wrapper for doc coverage.
• Config: Expanded lints/dictionary.

Fixed

• Docs build (strict): resolved broken/unknown links in TOOLING.md and removed duplicate API Reference sections; left sidebar now stays populated when deep-linking into API pages.
• Tests: E2E version fixtures cleaned up.

Packaging

• PyPI links corrected: project.urls now points to accurate Homepage/Docs/Changelog/Issues/Discussions.
• Dynamic versioning from Git tags: Using hatch-vcs with dynamic = ["version"]; annotated tags like v0.1.1 define the release version. commitizen tags as v$version.
• Richer PyPI description: hatch-fancy-pypi-readme renders README.md + CHANGELOG.md on PyPI.
• Wheel/Sdist layout: Explicit Hatch build config ensures py.typed, licenses, and metadata are included.

Back to top

---

0.1.0 – 2025-08-12

Added

• Core runtime

  • Implemented Dependency Injection kernel, REPL shell, plugin loader, telemetry hooks, and shell completion (bash/zsh/fish).
  • Added core modules: api, cli, httpapi, core/{constants,context,di,engine,enums,exceptions,paths}.

• Contracts layer (contracts/)

  • Defined protocols for audit, config, context, docs, doctor, emitter, history, memory, observability, process, registry, retry, serializer, telemetry.
  • Added py.typed markers for downstream type checking.

• Services layer

  • Implemented concrete services for audit, config, docs, doctor, history, memory.
  • Built plugin subsystem: plugins/{entrypoints,groups,hooks,registry}.

• Infra layer (infra/)

  • Implemented emitter, observability, process, retry, serializer, telemetry.

• Command suite

  • Added top-level commands: audit, docs, doctor, help, repl, sleep, status, version.
  • Added config/ commands: clear, export, get, list, load, reload, set, unset, service.
  • Added dev/ commands: di, list-plugins, service.
  • Added history/ commands: clear, service.
  • Added memory/ commands: clear, delete, get, list, set, service.
  • Added plugins/ commands: check, info, install, list, scaffold, uninstall.

• Structured output & flags

  • Added JSON/YAML output via --format, pretty printing, and deterministic global flag precedence (ADR-0002).

• API contract validation & testing

  • Automated lint/validation of api/*.yaml with Prance, OpenAPI Spec Validator, Redocly, and OpenAPI Generator.
  • Added Schemathesis contract testing against the running server.
  • Pinned OpenAPI Generator CLI version via OPENAPI_GENERATOR_VERSION and automated Node.js toolchain setup in Makefile.

• Documentation tooling

  • Integrated MkDocs (Material), mkdocstrings, literate-nav, and ADR index generation.

• Quality & security pipeline

  • Added formatting/linting: ruff (+format).
  • Added typing: mypy.
  • Added docs style/coverage: pydocstyle, interrogate.
  • Added code health: vulture, deptry, radon, codespell, reuse.
  • Added security: bandit, pip-audit.
  • Added mutation testing: mutmut, cosmic-ray.

• SBOM

  • Generated CycloneDX JSON for prod/dev dependencies via make sbom (uses pip-audit).

• Citation

  • Validated CITATION.cff and added export to BibTeX/RIS/EndNote formats via make citation.

• Makefile architecture

  • Modularized the Makefile into makefiles/*.mk for maintainability and clear separation of concerns.
  • Centralized all developer workflows (test, lint, quality, security, api, docs, build, sbom, citation, changelog, publish) in one consistent interface.
  • Added bootstrap target for idempotent virtualenv setup and Git hook installation from scripts/git-hooks (skips re-installation if already linked).
  • Added all-parallel target to run independent checks (quality, security, api, docs) concurrently for faster CI/CD.
  • Added make help for self-documenting targets with grouped sections.
  • Provided helper macros (run_tool, read_pyproject_version) to standardize tooling invocation.

• tox orchestration

  • Configured multi-Python test envs (py311, py312, py313).
  • Mapped Makefile workflows into tox envs (lint, quality, security, api, docs, build, sbom, changelog, citation) to ensure reproducibility.
  • Passed MAKEFLAGS to execute Makefile targets inside tox-managed virtualenvs.

• Continuous Integration

  • Added GitHub Actions workflow running tox across Python versions with Node.js 20 and Java 17 for API checks.
  • CI/CD pipelines directly leverage the modularized Makefile for consistent local/CI behavior.

• Packaging / PyPI page

  • Built dynamic long description via hatch-fancy-pypi-readme from README.md and CHANGELOG.md for PyPI/TestPyPI.
  • Packaged with LICENSES/, REUSE.toml, CITATION.cff, and py.typed included in source distributions.

Changed

• Released initial public version.

Fixed

• None

Back to top