| Name | bijux-cli JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | Lean, plug-in-driven CLI kernel |
| upload_time | 2025-08-14 18:35:51 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT License
Copyright (c) 2025 Bijan Mousavi
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
associated documentation files (the "Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial
portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
cli
dependency-injection
developer-tools
fastapi
pluggy
plugins
repl
typer
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Bijux CLI
<a id="top"></a>
**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.
[](https://pypi.org/project/bijux-cli/)
[](https://pypi.org/project/bijux-cli/)
[](https://raw.githubusercontent.com/bijux/bijux-cli/main/LICENSES/MIT.txt)
[](https://bijux.github.io/bijux-cli/)
[](https://github.com/bijux/bijux-cli/actions)
> **At a glance:** Plugin-driven • deterministic flags • DI for testability • REPL • structured JSON/YAML
> **Quality:** **2,600+ tests** across layers with **98%+ coverage**. Multi-version CI. Docs build enforced. No telemetry.
---
## Table of Contents
* [Why Bijux CLI?](#why-bijux-cli)
* [Try It in 20 Seconds](#try-it-in-20-seconds)
* [Key Features](#key-features)
* [Installation](#installation)
* [Quick Start](#quick-start)
* [Plugins in 60 Seconds](#plugins-in-60-seconds)
* [Structured Output](#structured-output)
* [Developer Introspection](#developer-introspection)
* [Global Flags: Strict Precedence](#global-flags-strict-precedence)
* [Built-in Commands](#built-in-commands)
* [When to Use (and Not Use)](#when-to-use-and-not-use)
* [Shell Completion](#shell-completion)
* [Configuration & Paths](#configuration--paths)
* [Tests & Quality](#tests--quality)
* [Project Tree](#project-tree)
* [Roadmap](#roadmap)
* [Docs & Resources](#docs--resources)
* [Contributing](#contributing)
* [Acknowledgments](#acknowledgments)
* [License](#license)
[Back to top](#top)
---
<a id="why-bijux-cli"></a>
## 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](#top)
---
<a id="try-it-in-20-seconds"></a>
## Try It in 20 Seconds
```bash
pipx install bijux-cli # Or: pip install bijux-cli
bijux --version
bijux doctor
bijux status -f json --no-pretty
```
[Back to top](#top)
---
<a id="key-features"></a>
## 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](#top)
---
<a id="installation"></a>
## Installation
Requires **Python 3.11+**.
```bash
# 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](#top)
---
<a id="quick-start"></a>
## Quick Start
```bash
# Discover commands/flags
bijux --help
# Health check
bijux doctor
# REPL mode
bijux
bijux> help
bijux> status
bijux> exit
```
[Back to top](#top)
---
<a id="plugins-in-60-seconds"></a>
## Plugins in 60 Seconds
```bash
# 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](#top)
---
<a id="structured-output"></a>
## Structured Output
For automation:
```bash
# Compact JSON
bijux status -f json --no-pretty | jq
# Pretty YAML
bijux status -f yaml --pretty
```
[Back to top](#top)
---
<a id="developer-introspection"></a>
## Developer Introspection
```bash
# DI graph
bijux dev di -f json
# Loaded plugins
bijux dev list-plugins
```
[Back to top](#top)
---
<a id="global-flags-strict-precedence"></a>
## 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](https://bijux.github.io/bijux-cli/ADR/0002-global-flags-precedence)
[Back to top](#top)
---
<a id="built-in-commands"></a>
## 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](#top)
---
<a id="when-to-use-and-not-use"></a>
## When to Use (and Not Use)
**Use if you need:**
* Plugins for extensibility.
* Deterministic flags for CI/scripts. [ADR-0002](https://bijux.github.io/bijux-cli/ADR/0002-global-flags-precedence)
* 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](#top)
---
<a id="shell-completion"></a>
## Shell Completion
```bash
# 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](#top)
---
<a id="configuration--paths"></a>
## 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:
```bash
export BIJUXCLI_PLUGINS_DIR=./custom-plugins
```
[Back to top](#top)
---
<a id="tests--quality"></a>
## 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](TESTS.md)**.
Quick commands:
```bash
make test # all tests
make test-unit # unit tests only
make test-e2e # end-to-end tests only
```
[Back to top](#top)
---
<a id="project-tree"></a>
## Project Tree
A guided map of the repository (what lives where, and why).
See **[PROJECT\_TREE.md](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](#top)
---
<a id="roadmap"></a>
## Roadmap
* **v0.2** — Async command support, richer plugin registry.
* **v1.0** — Community plugin marketplace, benchmarks vs. alternatives.
Track progress and suggest features via [Issues](https://github.com/bijux/bijux-cli/issues).
[Back to top](#top)
---
<a id="docs--resources"></a>
## Docs & Resources
* **Site**: [https://bijux.github.io/bijux-cli/](https://bijux.github.io/bijux-cli/)
* **Changelog**: [https://github.com/bijux/bijux-cli/blob/main/CHANGELOG.md](https://github.com/bijux/bijux-cli/blob/main/CHANGELOG.md)
* **Repository**: [https://github.com/bijux/bijux-cli](https://github.com/bijux/bijux-cli)
* **Issues**: [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](https://github.com/bijux/bijux-cli/security/advisories/new)
* **Tests:** See **[TESTS.md](TESTS.md)**
* **Project Tree:** See **[PROJECT\_TREE.md](PROJECT_TREE.md)**
*When filing issues, include `--debug` output where possible.*
[Back to top](#top)
---
<a id="contributing"></a>
## Contributing
Welcome! See **[CONTRIBUTING.md](https://github.com/bijux/bijux-cli/blob/main/CONTRIBUTING.md)** for setup, style, and tests. We label **good first issue** to help you get started.
[Back to top](#top)
---
<a id="acknowledgments"></a>
## Acknowledgments
* Built on [Typer](https://typer.tiangolo.com/) (CLI), [FastAPI](https://fastapi.tiangolo.com/) (HTTP API), and [Injector](https://github.com/python-injector/injector) (DI).
* Inspired by Click, Typer, and Cobra.
* Thanks to early contributors and testers!
[Back to top](#top)
---
<a id="license"></a>
## License
MIT — see **[LICENSES/MIT.txt](https://raw.githubusercontent.com/bijux/bijux-cli/main/LICENSES/MIT.txt)**.
© 2025 Bijan Mousavi.
[Back to top](#top)
# Changelog
<a id="top"></a>
All notable changes to **Bijux CLI** are documented here.
This project adheres to [Semantic Versioning](https://semver.org) and the
[Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.
<a id="unreleased"></a>
## [Unreleased]
### Added
* (add new entries via Towncrier fragments in `changelog.d/`)
### Changed
* (add here)
### Fixed
* (add here)
[Back to top](#top)
---
<!-- towncrier start -->
<a id="v0-1-1"></a>
## [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/helper_mkdocs.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](#top)
---
<a id="v0-1-0"></a>
## [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](https://bijux.github.io/bijux-cli/ADR/0002-global-flags-precedence)).
* **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`, `pyright`, `pytype`.
* 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.
* **pre-commit**
* Added hygiene hooks: `ruff-format` + `ruff`, `mdformat`, and `codespell`.
* Enforced Conventional Commits via **commitizen** `commit-msg` hook.
* **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.
* Added **GitLab CI** sample mirroring the GitHub workflow (tox-driven) with artifacts for coverage and API logs.
* 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](#top)
[Unreleased]: https://github.com/bijux/bijux-cli/compare/v0.1.1...HEAD
[0.1.1]: https://github.com/bijux/bijux-cli/compare/v0.1.0...v0.1.1
[0.1.0]: https://github.com/bijux/bijux-cli/releases/tag/v0.1.0
Raw data
{
"_id": null,
"home_page": null,
"name": "bijux-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "cli, dependency-injection, developer-tools, fastapi, pluggy, plugins, repl, typer",
"author": null,
"author_email": "Bijan Mousavi <mousavi.bijan@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/78/37/403cd0766ae8d25ede4966ead63aca732514081050aec55e4de3a4ede037/bijux_cli-0.1.1.tar.gz",
"platform": null,
"description": "# Bijux CLI\n<a id=\"top\"></a>\n\n**A modern, predictable CLI framework for Python** \u2014 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.\n\n[](https://pypi.org/project/bijux-cli/)\n[](https://pypi.org/project/bijux-cli/)\n[](https://raw.githubusercontent.com/bijux/bijux-cli/main/LICENSES/MIT.txt)\n[](https://bijux.github.io/bijux-cli/)\n[](https://github.com/bijux/bijux-cli/actions)\n\n> **At a glance:** Plugin-driven \u2022 deterministic flags \u2022 DI for testability \u2022 REPL \u2022 structured JSON/YAML \n> **Quality:** **2,600+ tests** across layers with **98%+ coverage**. Multi-version CI. Docs build enforced. No telemetry.\n\n---\n\n## Table of Contents\n\n* [Why Bijux CLI?](#why-bijux-cli)\n* [Try It in 20 Seconds](#try-it-in-20-seconds)\n* [Key Features](#key-features)\n* [Installation](#installation)\n* [Quick Start](#quick-start)\n* [Plugins in 60 Seconds](#plugins-in-60-seconds)\n* [Structured Output](#structured-output)\n* [Developer Introspection](#developer-introspection)\n* [Global Flags: Strict Precedence](#global-flags-strict-precedence)\n* [Built-in Commands](#built-in-commands)\n* [When to Use (and Not Use)](#when-to-use-and-not-use)\n* [Shell Completion](#shell-completion)\n* [Configuration & Paths](#configuration--paths)\n* [Tests & Quality](#tests--quality)\n* [Project Tree](#project-tree)\n* [Roadmap](#roadmap)\n* [Docs & Resources](#docs--resources)\n* [Contributing](#contributing)\n* [Acknowledgments](#acknowledgments)\n* [License](#license)\n\n[Back to top](#top)\n\n---\n\n<a id=\"why-bijux-cli\"></a>\n## Why Bijux CLI?\n\nClick and Typer excel at simple tools. Bijux emphasizes **predictability and modularity** for complex ones:\n\n* **Deterministic flags** for reliable CI/scripting.\n* **Dependency Injection kernel** for testable, decoupled services.\n* **First-class plugins** to extend without touching the core.\n* **Interactive REPL** for exploration and debugging.\n\n[Back to top](#top)\n\n---\n\n<a id=\"try-it-in-20-seconds\"></a>\n## Try It in 20 Seconds\n\n```bash\npipx install bijux-cli # Or: pip install bijux-cli\nbijux --version\nbijux doctor\nbijux status -f json --no-pretty\n```\n\n[Back to top](#top)\n\n---\n\n<a id=\"key-features\"></a>\n\n## Key Features\n\n* **Plugin-Driven Extensibility** \u2014 Scaffold, install, validate; plugins become top-level commands.\n* **Deterministic Behavior** \u2696 \u2014 Strict flag precedence (see ADR-0002).\n* **DI Kernel** \u2014 Decouple internals; inspect graphs for debugging/tests.\n* **REPL Shell** \u2014 Persistent session with history; great for exploration/demos.\n* **Structured Output** \u2014 JSON/YAML (+ pretty/compact, verbosity, consistent errors).\n* **Diagnostics** \u2014 Built-in `doctor`, `audit`, `docs` for workflows.\n* **Shell Completion** \u2014 Bash, Zsh, Fish, PowerShell support.\n\n[Back to top](#top)\n\n---\n\n<a id=\"installation\"></a>\n\n## Installation\n\nRequires **Python 3.11+**.\n\n```bash\n# Isolated install (recommended)\npipx install bijux-cli\n\n# Standard\npip install bijux-cli\n```\n\nUpgrade: `pipx upgrade bijux-cli` or `pip install --upgrade bijux-cli`.\n\n[Back to top](#top)\n\n---\n\n<a id=\"quick-start\"></a>\n\n## Quick Start\n\n```bash\n# Discover commands/flags\nbijux --help\n\n# Health check\nbijux doctor\n\n# REPL mode\nbijux\nbijux> help\nbijux> status\nbijux> exit\n```\n\n[Back to top](#top)\n\n---\n\n<a id=\"plugins-in-60-seconds\"></a>\n\n## Plugins in 60 Seconds\n\n```bash\n# Scaffold from a real template (local dir or Git URL), then install\n# Option A: local template (example uses repo's cookiecutter template)\nbijux plugins scaffold my_plugin --template ./plugin_template --force\n\n# Option B: cookiecutter-compatible Git URL\n# bijux plugins scaffold my_plugin --template https://github.com/bijux/bijux-plugin-template.git --force\n\n# Install & explore\nbijux plugins install ./my_plugin --force\nbijux plugins list\nbijux my_plugin --help\n\n# Validate & remove\nbijux plugins check my_plugin\nbijux plugins uninstall my_plugin\n```\n\nPlugins dynamically add top-level commands.\n\n[Back to top](#top)\n\n---\n\n<a id=\"structured-output\"></a>\n\n## Structured Output\n\nFor automation:\n\n```bash\n# Compact JSON\nbijux status -f json --no-pretty | jq\n\n# Pretty YAML\nbijux status -f yaml --pretty\n```\n\n[Back to top](#top)\n\n---\n\n<a id=\"developer-introspection\"></a>\n\n## Developer Introspection\n\n```bash\n# DI graph\nbijux dev di -f json\n\n# Loaded plugins\nbijux dev list-plugins\n```\n\n[Back to top](#top)\n\n---\n\n<a id=\"global-flags-strict-precedence\"></a>\n\n## Global Flags: Strict Precedence\n\nFixed ordering eliminates ambiguity.\n\n| Priority | Flag | Effect |\n| -------: | --------------------------- | --------------------------------------------------------- |\n| 1 | `-h`, `--help` | Immediate exit (code 0) with usage; ignores all. |\n| 2 | `-q`, `--quiet` | Suppress stdout/stderr; preserves exit code. |\n| 3 | `-d`, `--debug` | Full diagnostics; implies `--verbose`, forces `--pretty`. |\n| 4 | `-f, --format <json\\|yaml>` | Structured output; invalid \u2192 code 2. |\n| 5 | `--pretty` / `--no-pretty` | Indentation toggle (default: `--pretty`). |\n| 6 | `-v`, `--verbose` | Runtime metadata; implied by `--debug`. |\n\nRationale: [ADR-0002](https://bijux.github.io/bijux-cli/ADR/0002-global-flags-precedence)\n\n[Back to top](#top)\n\n---\n\n<a id=\"built-in-commands\"></a>\n\n## Built-in Commands\n\n| Command | Description | Example |\n| --------- | --------------------------- | --------------------------------- |\n| `doctor` | Environment diagnostics | `bijux doctor` |\n| `status` | CLI snapshot | `bijux status -f json` |\n| `repl` | Interactive shell | `bijux repl` |\n| `plugins` | Manage plugins | `bijux plugins list` |\n| `config` | Key-value settings | `bijux config set core_timeout=5` |\n| `history` | REPL history | `bijux history --limit 10` |\n| `audit` | Security checks | `bijux audit --dry-run` |\n| `docs` | Generate specs/docs | `bijux docs --out spec.json` |\n| `dev` | Introspection (DI, plugins) | `bijux dev di` |\n| `sleep` | Pause | `bijux sleep -s 5` |\n| `version` | Version info | `bijux version` |\n\n[Back to top](#top)\n\n---\n\n<a id=\"when-to-use-and-not-use\"></a>\n\n## When to Use (and Not Use)\n\n**Use if you need:**\n\n* Plugins for extensibility.\n* Deterministic flags for CI/scripts. [ADR-0002](https://bijux.github.io/bijux-cli/ADR/0002-global-flags-precedence)\n* REPL for interactive workflows.\n* DI for modular, testable design.\n\n**Overkill if:**\n\n* You\u2019re building a tiny one-off script (Click/Typer may be simpler).\n* You don\u2019t need plugins/DI.\n\n[Back to top](#top)\n\n---\n\n<a id=\"shell-completion\"></a>\n\n## Shell Completion\n\n```bash\n# Install (writes to your shell\u2019s completion dir)\nbijux --install-completion\n\n# Or print the script for manual setup\nbijux --show-completion\n```\n\n*Zsh tip:* Ensure `compinit` runs and your `fpath` includes the completion directory.\n\n[Back to top](#top)\n\n---\n\n<a id=\"configuration--paths\"></a>\n\n## Configuration & Paths\n\nPrecedence: **flags > env > config > defaults**.\n\n* Config: `~/.bijux/.env` (`BIJUXCLI_CONFIG`)\n* History: `~/.bijux/.history` (`BIJUXCLI_HISTORY_FILE`)\n* Plugins: `~/.bijux/.plugins` (`BIJUXCLI_PLUGINS_DIR`)\n\nExample:\n\n```bash\nexport BIJUXCLI_PLUGINS_DIR=./custom-plugins\n```\n\n[Back to top](#top)\n\n---\n\n<a id=\"tests--quality\"></a>\n\n## Tests & Quality\n\n* **Depth:** 2,600+ tests across unit, integration, functional, and E2E layers.\n* **Coverage:** **98%+** code coverage (measured via `pytest-cov` in CI).\n* **Determinism:** CI runs the full suite on multiple Python versions (3.11+).\n* **Artifacts:** JSON/YAML fixtures validate structured outputs; E2E simulates real usage (REPL, plugins, DI).\n* **Docs:** Read the full testing guide \u2192 **[TESTS.md](TESTS.md)**.\n\nQuick commands:\n\n```bash\nmake test # all tests\nmake test-unit # unit tests only\nmake test-e2e # end-to-end tests only\n```\n\n[Back to top](#top)\n\n---\n\n<a id=\"project-tree\"></a>\n\n## Project Tree\n\nA guided map of the repository (what lives where, and why).\nSee **[PROJECT\\_TREE.md](PROJECT_TREE.md)** for the full breakdown.\n\nQuick glance:\n\n```\napi/ # OpenAPI schemas\nconfig/ # Lint/type/security configs\ndocs/ # MkDocs site (Material)\nmakefiles/ # Task modules (docs, test, lint, etc.)\nplugin_template/# Cookiecutter-ready plugin scaffold\nscripts/ # Helper scripts (hooks, docs generation)\nsrc/bijux_cli/ # CLI + library implementation\ntests/ # unit / integration / functional / e2e\n```\n\n[Back to top](#top)\n\n---\n\n<a id=\"roadmap\"></a>\n\n## Roadmap\n\n* **v0.2** \u2014 Async command support, richer plugin registry.\n* **v1.0** \u2014 Community plugin marketplace, benchmarks vs. alternatives.\n\nTrack progress and suggest features via [Issues](https://github.com/bijux/bijux-cli/issues).\n\n[Back to top](#top)\n\n---\n\n<a id=\"docs--resources\"></a>\n\n## Docs & Resources\n\n* **Site**: [https://bijux.github.io/bijux-cli/](https://bijux.github.io/bijux-cli/)\n* **Changelog**: [https://github.com/bijux/bijux-cli/blob/main/CHANGELOG.md](https://github.com/bijux/bijux-cli/blob/main/CHANGELOG.md)\n* **Repository**: [https://github.com/bijux/bijux-cli](https://github.com/bijux/bijux-cli)\n* **Issues**: [https://github.com/bijux/bijux-cli/issues](https://github.com/bijux/bijux-cli/issues)\n* **Security** (private reports): [https://github.com/bijux/bijux-cli/security/advisories/new](https://github.com/bijux/bijux-cli/security/advisories/new)\n* **Tests:** See **[TESTS.md](TESTS.md)**\n* **Project Tree:** See **[PROJECT\\_TREE.md](PROJECT_TREE.md)**\n\n*When filing issues, include `--debug` output where possible.*\n\n[Back to top](#top)\n\n---\n\n<a id=\"contributing\"></a>\n\n## Contributing\n\nWelcome! See **[CONTRIBUTING.md](https://github.com/bijux/bijux-cli/blob/main/CONTRIBUTING.md)** for setup, style, and tests. We label **good first issue** to help you get started.\n\n[Back to top](#top)\n\n---\n\n<a id=\"acknowledgments\"></a>\n\n## Acknowledgments\n\n* Built on [Typer](https://typer.tiangolo.com/) (CLI), [FastAPI](https://fastapi.tiangolo.com/) (HTTP API), and [Injector](https://github.com/python-injector/injector) (DI).\n* Inspired by Click, Typer, and Cobra.\n* Thanks to early contributors and testers!\n\n[Back to top](#top)\n\n---\n\n<a id=\"license\"></a>\n\n## License\n\nMIT \u2014 see **[LICENSES/MIT.txt](https://raw.githubusercontent.com/bijux/bijux-cli/main/LICENSES/MIT.txt)**.\n\u00a9 2025 Bijan Mousavi.\n\n[Back to top](#top)\n# Changelog\n<a id=\"top\"></a>\n\nAll notable changes to **Bijux CLI** are documented here.\nThis project adheres to [Semantic Versioning](https://semver.org) and the\n[Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.\n\n<a id=\"unreleased\"></a>\n## [Unreleased]\n\n### Added\n* (add new entries via Towncrier fragments in `changelog.d/`)\n\n### Changed\n* (add here)\n\n### Fixed\n* (add here)\n\n[Back to top](#top)\n\n---\n\n<!-- towncrier start -->\n\n<a id=\"v0-1-1\"></a>\n## [0.1.1] \u2013 2025-08-14\n\n### Added\n* **Publish pipeline:** GitHub Actions `publish.yml` that publishes via `make publish` only after required checks are green and a tag is present.\n* **Project map:** `PROJECT_TREE.md` (and `docs/project_tree.md`) with a curated overview.\n* **Developer Tooling page:** `TOOLING.md` (and `docs/tooling.md`) with embedded configs, Makefile snippets, and CI workflows via `include-markdown`.\n* **Docs assets:** Community landing page, Plausible analytics partial, and CSS overrides.\n\n### Changed\n* **Docs generator (`scripts/helper_mkdocs.py`):**\n * Copies **README**, **USAGE**, **TESTS**, **PROJECT_TREE**, and **TOOLING** into the site with link rewrites and `{#top}` anchors.\n * Generates mkdocstrings pages for all modules under `src/bijux_cli/**`.\n * Builds **one** consolidated **API Reference** with this structure:\n * top: **Api Module**, **Cli Module**, **Httpapi Module**\n * sections (collapsed by default): **Commands**, **Contracts**, **Core**, **Infra**, **Services**\n * nested groups for command subpackages (`config/`, `dev/`, `history/`, `memory/`, `plugins/`) beneath **Commands**.\n * Emits `reference/**/index.md` to power Material\u2019s section indexes.\n* **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.\n* **README / USAGE:** Refined copy; standardized **top anchors** and links to **TESTS.md**/**PROJECT_TREE.md**/**TOOLING.md**.\n* **SECURITY.md:** Rewritten with clearer reporting, SLAs, scope, and safe harbor.\n* **Makefiles:** macOS-safe env handling; Cairo-less Interrogate wrapper for doc coverage.\n* **Config:** Expanded lints/dictionary.\n\n### Fixed\n* **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.\n* **Tests:** E2E version fixtures cleaned up.\n\n### Packaging\n* **PyPI links corrected:** `project.urls` now points to accurate Homepage/Docs/Changelog/Issues/Discussions.\n* **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`.\n* **Richer PyPI description:** `hatch-fancy-pypi-readme` renders **README.md** + **CHANGELOG.md** on PyPI.\n* **Wheel/Sdist layout:** Explicit Hatch build config ensures `py.typed`, licenses, and metadata are included.\n\n[Back to top](#top)\n\n---\n\n<a id=\"v0-1-0\"></a>\n## [0.1.0] \u2013 2025-08-12\n\n### Added\n\n* **Core runtime**\n\n * Implemented Dependency Injection kernel, REPL shell, plugin loader, telemetry hooks, and shell completion (bash/zsh/fish).\n * Added core modules: `api`, `cli`, `httpapi`, `core/{constants,context,di,engine,enums,exceptions,paths}`.\n\n* **Contracts layer** (`contracts/`)\n\n * Defined protocols for `audit`, `config`, `context`, `docs`, `doctor`, `emitter`, `history`,\n `memory`, `observability`, `process`, `registry`, `retry`, `serializer`, `telemetry`.\n * Added `py.typed` markers for downstream type checking.\n\n* **Services layer**\n\n * Implemented concrete services for `audit`, `config`, `docs`, `doctor`, `history`, `memory`.\n * Built plugin subsystem: `plugins/{entrypoints,groups,hooks,registry}`.\n\n* **Infra layer** (`infra/`)\n\n * Implemented `emitter`, `observability`, `process`, `retry`, `serializer`, `telemetry`.\n\n* **Command suite**\n\n * Added top-level commands: `audit`, `docs`, `doctor`, `help`, `repl`, `sleep`, `status`, `version`.\n * Added `config/` commands: `clear`, `export`, `get`, `list`, `load`, `reload`, `set`, `unset`, `service`.\n * Added `dev/` commands: `di`, `list-plugins`, `service`.\n * Added `history/` commands: `clear`, `service`.\n * Added `memory/` commands: `clear`, `delete`, `get`, `list`, `set`, `service`.\n * Added `plugins/` commands: `check`, `info`, `install`, `list`, `scaffold`, `uninstall`.\n\n* **Structured output & flags**\n\n * Added JSON/YAML output via `--format`, pretty printing, and deterministic global flag precedence ([ADR-0002](https://bijux.github.io/bijux-cli/ADR/0002-global-flags-precedence)).\n\n* **API contract validation & testing**\n\n * Automated lint/validation of `api/*.yaml` with Prance, OpenAPI Spec Validator, Redocly, and OpenAPI Generator.\n * Added **Schemathesis** contract testing against the running server.\n * Pinned OpenAPI Generator CLI version via `OPENAPI_GENERATOR_VERSION` and automated Node.js toolchain setup in Makefile.\n\n* **Documentation tooling**\n\n * Integrated MkDocs (Material), mkdocstrings, literate-nav, and ADR index generation.\n\n* **Quality & security pipeline**\n\n * Added formatting/linting: `ruff` (+format).\n * Added typing: `mypy`, `pyright`, `pytype`.\n * Added docs style/coverage: `pydocstyle`, `interrogate`.\n * Added code health: `vulture`, `deptry`, `radon`, `codespell`, `reuse`.\n * Added security: `bandit`, `pip-audit`.\n * Added mutation testing: `mutmut`, `cosmic-ray`.\n\n* **SBOM**\n\n * Generated CycloneDX JSON for prod/dev dependencies via `make sbom` (uses `pip-audit`).\n\n* **Citation**\n\n * Validated `CITATION.cff` and added export to BibTeX/RIS/EndNote formats via `make citation`.\n\n* **Makefile architecture**\n\n * Modularized the Makefile into `makefiles/*.mk` for maintainability and clear separation of concerns.\n * Centralized all developer workflows (`test`, `lint`, `quality`, `security`, `api`, `docs`, `build`, `sbom`, `citation`, `changelog`, `publish`) in one consistent interface.\n * Added `bootstrap` target for idempotent virtualenv setup and Git hook installation from `scripts/git-hooks` (skips re-installation if already linked).\n * Added `all-parallel` target to run independent checks (`quality`, `security`, `api`, `docs`) concurrently for faster CI/CD.\n * Added `make help` for self-documenting targets with grouped sections.\n * Provided helper macros (`run_tool`, `read_pyproject_version`) to standardize tooling invocation.\n\n* **pre-commit**\n\n * Added hygiene hooks: `ruff-format` + `ruff`, `mdformat`, and `codespell`.\n * Enforced Conventional Commits via **commitizen** `commit-msg` hook.\n\n* **tox orchestration**\n\n * Configured multi-Python test envs (`py311`, `py312`, `py313`).\n * Mapped Makefile workflows into tox envs (`lint`, `quality`, `security`, `api`, `docs`, `build`, `sbom`, `changelog`, `citation`) to ensure reproducibility.\n * Passed `MAKEFLAGS` to execute Makefile targets inside tox-managed virtualenvs.\n\n* **Continuous Integration**\n\n * Added **GitHub Actions** workflow running tox across Python versions with Node.js 20 and Java 17 for API checks.\n * Added **GitLab CI** sample mirroring the GitHub workflow (tox-driven) with artifacts for coverage and API logs.\n * CI/CD pipelines directly leverage the modularized Makefile for consistent local/CI behavior.\n\n* **Packaging / PyPI page**\n\n * Built dynamic long description via **hatch-fancy-pypi-readme** from **README.md** and **CHANGELOG.md** for PyPI/TestPyPI.\n * Packaged with `LICENSES/`, `REUSE.toml`, `CITATION.cff`, and `py.typed` included in source distributions.\n\n### Changed\n\n* Released initial public version.\n\n### Fixed\n\n* None\n\n[Back to top](#top)\n\n[Unreleased]: https://github.com/bijux/bijux-cli/compare/v0.1.1...HEAD\n[0.1.1]: https://github.com/bijux/bijux-cli/compare/v0.1.0...v0.1.1\n[0.1.0]: https://github.com/bijux/bijux-cli/releases/tag/v0.1.0\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Bijan Mousavi\n \n Permission is hereby granted, free of charge, to any person obtaining a copy of this software and\n associated documentation files (the \"Software\"), to deal in the Software without restriction, including\n without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the\n following conditions:\n \n The above copyright notice and this permission notice shall be included in all copies or substantial\n portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT\n LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO\n EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\n IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE\n USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "Lean, plug-in-driven CLI kernel",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/bijux/bijux-cli/issues",
"Changelog": "https://bijux.github.io/bijux-cli/changelog/",
"Discussions": "https://github.com/bijux/bijux-cli/discussions",
"Documentation": "https://bijux.github.io/bijux-cli/",
"Homepage": "https://github.com/bijux/bijux-cli",
"Repository": "https://github.com/bijux/bijux-cli.git"
},
"split_keywords": [
"cli",
" dependency-injection",
" developer-tools",
" fastapi",
" pluggy",
" plugins",
" repl",
" typer"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ce88a584827d93001b1dc08a1e4b9d6e8e17a1cda18ce3695a90c984ab5d2951",
"md5": "42b7e5c94393896989c28f63440460df",
"sha256": "4a058efcad738e2ef84cdac4292966629b8ae01fb7f3bbee3c73094841b6fe78"
},
"downloads": -1,
"filename": "bijux_cli-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "42b7e5c94393896989c28f63440460df",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 204620,
"upload_time": "2025-08-14T18:35:49",
"upload_time_iso_8601": "2025-08-14T18:35:49.882633Z",
"url": "https://files.pythonhosted.org/packages/ce/88/a584827d93001b1dc08a1e4b9d6e8e17a1cda18ce3695a90c984ab5d2951/bijux_cli-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7837403cd0766ae8d25ede4966ead63aca732514081050aec55e4de3a4ede037",
"md5": "d45371ce63ed7ca854f7525022d1cd86",
"sha256": "c41c1b4f9c692ad7193b2cfb1a6aa0d680851c614a4142da5126084a00ddf1e9"
},
"downloads": -1,
"filename": "bijux_cli-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "d45371ce63ed7ca854f7525022d1cd86",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 23931,
"upload_time": "2025-08-14T18:35:51",
"upload_time_iso_8601": "2025-08-14T18:35:51.059333Z",
"url": "https://files.pythonhosted.org/packages/78/37/403cd0766ae8d25ede4966ead63aca732514081050aec55e4de3a4ede037/bijux_cli-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-14 18:35:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bijux",
"github_project": "bijux-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "bijux-cli"
}
