Skip to content
v0.1.3

Bijux CLI — User Guide

A practical reference for installation, global flags, commands, configuration, and behavior. For a project overview and motivation, see the README on GitHub: https://github.com/bijux/bijux-cli

Table of Contents

Back to top

Installation

Requires Python 3.11+.

pipx install bijux-cli
pipx ensurepath       # first-time pipx users
# later
pipx upgrade bijux-cli

pip

python -m pip install -U bijux-cli

Tip: use a virtual environment when installing with plain pip.

Back to top

Quick Start

bijux --help          # commands and global flags
bijux --version       # version/sanity
bijux doctor          # environment diagnostics

# REPL
bijux
bijux> help
bijux> status -f json   # {"version":"<current>", ...}
bijux> exit

Back to top

Shell Completion

bijux --install-completion   # install for your current shell
bijux --show-completion      # print the script for manual setup

Shell notes:

  • Bash (current session): eval "$(bijux --show-completion)"

  • Zsh (persistent): add to ~/.zshrc:

  • fpath+=("$HOME/.zfunc")

  • autoload -U compinit && compinit
  • then run bijux --install-completion
  • Fish / PowerShell: run --install-completion

Restart your shell after installing. For Zsh, ensure compinit runs and your fpath includes the completions directory.

Back to top

Global Flags – Precedence

Flags are evaluated in strict order; higher priority short-circuits lower ones.

Priority Flag(s) Behavior
1 -h, --help Exit 0 with usage; ignore all other flags.
2 -q, --quiet Suppress stdout/stderr; exit code still reflects result.
3 -d, --debug Full diagnostics; implies --verbose and forces --pretty.
4 -f, --format <json\|yaml> Structured output; invalid value → exit code 2.
5 --pretty / --no-pretty Indentation control (default: --pretty).
6 -v, --verbose Include runtime metadata; implied by --debug.

Details: ADR-0002 (Global Flags Precedence) — https://bijux.github.io/bijux-cli/ADR/0002-global-flags-precedence

When --format is set, errors are emitted in that format to stderr (unless --quiet).

Back to top

Command Reference

config — Settings

Dotenv-style key/value settings. Keys must be alphanumeric or underscore.

  • list → {"items":[{"key":"...","value":"..."}]}

bijux config list -f json --no-pretty
* get <key> → {"value":"..."}

bijux config get core_timeout
* set <key=value> / unset <key>

bijux config set core_timeout=30
bijux config unset core_timeout
* export <path> (supports -f json|yaml)

bijux config export ./settings.env
bijux config export ./settings.json -f json
* load <path> (dotenv), reload, clear

Tip: Use -f json --no-pretty for machine-readable output in scripts.

Back to top

plugins — Plugin Management

Default install dir: ~/.bijux/.plugins (override via BIJUXCLI_PLUGINS_DIR).

  • list → {"plugins":["...", ...]}

bijux plugins list
* info <name|path>, check <name|path>, uninstall <name> * install <path> — install a plugin directory (use --force to overwrite)

bijux plugins install ./path/to/my_plugin --force
* scaffold <name> --template <path-or-git-url> — create a plugin from a template

# Requires a real template (local dir or cookiecutter-compatible Git URL)
bijux plugins scaffold my_plugin --template ./templates/bijux-plugin --force
# or
bijux plugins scaffold my_plugin --template https://github.com/bijux/bijux-plugin-template.git --force

scaffold requires --template. Without it you’ll get no_template. --force overwrites files in the destination.

Back to top

history — REPL History

  • list (supports --limit, --group-by, --filter, --sort) → {"entries":[...]}

bijux history --limit 10 -f json --no-pretty
* --export <path>, --import <path>, clear

Back to top

dev — Developer Tools

  • di → {"factories":[...],"services":[...]}

bijux dev di -f json
* list-plugins — diagnostic list of discovered plugins

Back to top

Built-in Commands (Index)

Command Purpose Example (sample output)
audit Security/compliance checks bijux audit --dry-run → {"issues":[...]}
docs Generate specs/docs bijux docs --out spec.json → writes file
doctor Health diagnostics bijux doctor → summary or detailed findings
memory Key-value store bijux memory set key=val → {"status":"set"}
repl Interactive shell bijux repl → interactive bijux> prompt
sleep Pause execution bijux sleep -s 5 → pauses for 5 seconds
status CLI status snapshot bijux status -f json → {"version":"<current>", ...}
version Version info bijux version → <current>

Plugins appear as additional top-level commands after install.

Back to top

Advanced Usage Patterns

  • Batch config apply:

bijux config set core_timeout=30 && bijux config reload
* Check all installed plugins:

bijux plugins list -f json --no-pretty \
  | jq -r '.plugins[]' \
  | xargs -I {} bijux plugins check {}
* Diagnostics pipeline:

bijux doctor --debug > diag.log
bijux status -d >> diag.log

Combine with --quiet in CI to suppress output while preserving exit codes.

Back to top

Configuration

Default paths (overridable via environment variables):

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

Override example (shell profile):

export BIJUXCLI_PLUGINS_DIR=./plugins

Resolution precedence:

  1. CLI flags → 2) Environment variables → 3) Config file → 4) Defaults

Back to top

End-to-End Workflows

Core Workflow (no plugins)

This flow works on any install; it does not assume a template or extra files.

# Fresh artifacts_pages directory
rm -rf artifacts_pages && mkdir -p artifacts_pages

# Version and health
bijux --version
bijux doctor

# Config operations
bijux config set core_timeout=30
bijux config get core_timeout                 # {"value":"30"}
bijux config list -f json --no-pretty > artifacts_pages/config.json
bijux config export artifacts_pages/settings.env
bijux config export artifacts_pages/settings.json -f json

# REPL creates history
bijux repl <<'EOF'
version
help
exit
EOF

# History operations
bijux history --limit 5 -f json --no-pretty > artifacts_pages/history.json
bijux history --export artifacts_pages/history-full.json
bijux history --import artifacts_pages/history-full.json

# Cleanup
bijux history clear
bijux config clear

Plugin Workflow (requires a real template)

Choose one:

# Start clean
bijux plugins uninstall my_plugin || true
rm -rf tmp && mkdir -p tmp

# Scaffold (requires a real template path or Git URL)
# Option A: local template directory
bijux plugins scaffold my_plugin --template ./templates/bijux-plugin --force

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

# Install the newly scaffolded plugin
bijux plugins install ./my_plugin --force

# Verify & validate
bijux plugins list                     # {"plugins":["my_plugin", ...]}
bijux plugins info my_plugin
bijux plugins check my_plugin

# Uninstall when done
bijux plugins uninstall my_plugin || true

If you do not provide a real template, scaffold will fail with no_template, and subsequent install/info/check will also fail.

Back to top

Structured Error Model

With --format, errors are structured and written to stderr (unless --quiet):

{
  "error": "message",
  "code": 2,
  "failure": "machine_readable_reason",
  "command": "subcommand path",
  "fmt": "json"
}

(YAML is emitted when -f yaml is used.)

Back to top

Exit Codes

Code Meaning
0 Success
1 General/internal error
2 Usage/invalid argument
3 Encoding/hygiene error

Commands may define additional non-conflicting codes.

Back to top

Troubleshooting & FAQs

  • Start with bijux doctor.
  • Need more detail? Use --verbose or --debug (adds pretty printing and diagnostics).
  • Scripting? Prefer -f json --no-pretty and read from stdout; errors go to stderr.
  • Completion not working? Re-run --install-completion and restart the shell; ensure Zsh compinit and fpath are correct.
  • Permission denied? Ensure paths are writable; avoid sudo unless absolutely required.

  • Plugin errors?

  • no_template: pass a real --template (path or Git URL) to plugins scaffold.

  • not_found / not_installed: confirm plugin name; check bijux plugins list.
  • Use bijux plugins check <name> after installing.
  • Bug reports: include --debug output, version (bijux --version), OS, and repro steps.

Back to top