bijux-cli 0.1.0

Lean, plug-in-driven CLI kernel

Bijux CLI

A modern, predictable, and extensible CLI framework — with strict runtime contracts, a first-class plugin system, structured output, and built-in diagnostics.

---

Features at a Glance

• Plugin-driven architecture – add/override behavior without touching core.
• Deterministic global flags – strict precedence for consistent behavior (see ADR: Global Flags Precedence).
• Dependency-Injection kernel – decoupled services, easy to test.
• Interactive REPL – persistent shell for exploration and debugging.
• Structured output – JSON/YAML with pretty/compact controls.
• Diagnostics – environment checks, DI graph inspection, plugin validation.

---

Installation

Requires Python 3.11+

# Recommended: isolated CLI install
pipx install bijux-cli

# Or via pip
pip install bijux-cli

---

Quick Start

# See commands and global flags
bijux --help

# Run environment diagnostics
bijux doctor

# Start the interactive shell
bijux
bijux> help
bijux> exit

---

Usage Examples

Structured Output (JSON/YAML)

# Compact JSON for scripting
bijux status -f json --no-pretty

# Pretty JSON for humans
bijux status -f json --pretty

# YAML
bijux status -f yaml

DI & Developer Introspection

# Inspect DI registrations
bijux dev di -f json | jq

# List loaded plugins
bijux dev list-plugins

Plugins

# Scaffold, install, and validate a plugin
mkdir -p ./tmp_plugin && cd ./tmp_plugin
bijux plugins scaffold my_plugin --template=../plugin_template --force
cd ..
bijux plugins install ./tmp_plugin/my_plugin --force
bijux plugins check my_plugin
bijux plugins list

---

Global Flags (Precedence)

Higher priority wins and may short-circuit lower ones.

Priority	Flag(s)	Effect
1	-h, --help	Exit 0 immediately; ignore all other flags.
2	-q, --quiet	Suppress both stdout and stderr; exit code still reflects the result.
3	-d, --debug	Full diagnostics; implies --verbose, forces --pretty.
4	-f, --format <json|yaml>	Choose structured output; invalid value → exit code 2.
5	--pretty/--no-pretty	Control indentation (default: --pretty).
6	-v, --verbose	Add runtime metadata; implied by --debug.

Reference: ADR-0002 Global Flags Precedence https://bijux.github.io/bijux-cli/ADR/0002-global-flags-precedence/

---

Built-in Commands

Command	Purpose	Example
doctor	Environment health check	bijux doctor
status	Show CLI status	bijux status -f json
repl	Interactive shell	bijux repl
plugins	Manage plugins	bijux plugins list
config	Manage key-value settings	bijux config set core_timeout=5
history	REPL history operations	bijux history --limit 10
audit	Security/compliance audit	bijux audit --dry-run
docs	Docs/spec generation utilities	bijux docs --out spec.json
dev	Developer tools (DI, plugins)	bijux dev di
sleep	Pause execution	bijux sleep -s 5
version	Display version info	bijux version

Plugins are surfaced as top-level commands once installed.

---

Shell Completion

Enable tab completion (no sudo required):

# Install completion (zsh saves to ~/.zfunc)
bijux --install-completion

# Or print the script if you manage completions manually
bijux --show-completion

Restart your shell afterward. For zsh, ensure compinit runs and your fpath includes the completions' directory.

---

Configuration & Paths

Defaults (overridable via env vars):

• Config: ~/.bijux/.env → BIJUXCLI_CONFIG
• History: ~/.bijux/.history → BIJUXCLI_HISTORY_FILE
• Plugins: ~/.bijux/.plugins → BIJUXCLI_PLUGINS_DIR

Resolution order: CLI flags → Environment → Config file → Defaults

Example override:

export BIJUXCLI_PLUGINS_DIR=./.plugins
export BIJUXCLI_CONFIG=./.env
export BIJUXCLI_HISTORY_FILE=./.history

---

Documentation

• User Guide: https://bijux.github.io/bijux-cli/usage/
• Contributing: https://bijux.github.io/bijux-cli/contributing/
• Security Policy: https://bijux.github.io/bijux-cli/security/
• Code of Conduct: https://bijux.github.io/bijux-cli/code_of_conduct/

---

Support & Security

• Issues: please include --debug output where feasible.
• Vulnerabilities: report privately via GitHub Security Advisory. https://github.com/bijux/bijux-cli/security/advisories/new

---

License

Released under the MIT License. https://bijux.github.io/bijux-cli/license/