Skip to content

Latest commit

 

History

History
815 lines (650 loc) · 33.6 KB

commands.md

File metadata and controls

815 lines (650 loc) · 33.6 KB

CLI Reference

Overview

baller <COMMAND> [ARGS] [FLAGS]

All commands are sports-themed. Colored output via the colored crate.


Global Flags

These work on every subcommand and may appear before or after it — baller -y eject fd and baller eject fd -y are the same command.

Flag Description
--yes, -y Skip confirmation prompts (eject, sweep, substitute, inject); required for them under --json
--quiet, -q Suppress progress bars and step-by-step output; a command's result (a table, a report, version) is still printed
--verbose, -v Increase output detail: resolved URLs, source chains and cache paths on stderr. roster prints full detail blocks
--json Emit machine-readable JSON instead of formatted text; implies quiet
--no-hooks Skip every pre/post install, eject and update hook
--no-color Disable colored output (useful in CI)
--config <DIR> Use an alternate baller directory; db, cache and hooks all derive from it
--no-referee Skip the Referee security checks (both phases) for this run — see referee.md

--json prints a single JSON document on stdout and suppresses every other print, so command output stays parseable. That holds for every path:

  • help, help <command>, version, and -h/--help/-V/--version combined with --json, print JSON documents (see help and version).
  • A failure prints {"command": …, "error": …, "code": …} on stdout instead of [Error]: … on stderr, and still exits 1 — see error-handling.md.
  • Confirmation prompts are never shown: a command that would prompt fails with a ConfirmationRequired error instead, so pass --yes to run eject, sweep, substitute or inject under --json.
  • Programs baller runs on the way — hook scripts, apt-get/dnf/pacman for system packages, cargo install — still run, but their output goes to stderr instead of stdout. (An injected command's output is its own, and passes straight through.)

Progress lines and verbose detail are written to stderr; stdout carries only the data a command produces. -v raises the detail level, -q and --json silence it entirely, so baller --json roster > out.json yields a file holding nothing but JSON.


draft — Install a Package

baller draft <package_name> [--version <V>] [--source <S>] [--no-deps] [--dry-run] [-f]

Fetches the package and all its transitive dependencies from the registry chain, downloads, verifies the package hash (SHA-256 for GitHub/Baller, SHA-512 for Chocolatey), extracts, symlinks the binary, and records in the SQLite database.

Referee checks the whole resolved plan against public vulnerability data before the install loop starts, and scans each extracted archive before its binary is linked. A blocked plan installs nothing at all; --no-referee skips both checks. See referee.md.

Flags:

Flag Description
--version <V> Pin an exact version. GitHub and Chocolatey only — the Baller registry does not support pinning yet, and system and cargo packages always install the latest
--source <S> Resolve from one registry (github, baller, chocolatey, system, cargo) instead of the configured chain. system is Linux-only and chocolatey is Windows-only — either one on the other platform fails before anything is fetched; cargo needs a cargo toolchain on PATH
--no-deps Install the root package alone
--dry-run Print the resolved plan (every package, version, source and action) and change nothing. A package in the plan that this host cannot install (a Windows-only source on Linux, say) fails the dry run too
--force, -f Reinstall even when the package is already on the roster (without it, installed packages are skipped)

--version and --source combine: --source github --version 14.1.0 pins against GitHub alone. Dependencies still resolve through the normal chain.

$ baller draft BurntSushi/ripgrep --source github --dry-run
Dry run ripgrep v15.2.0 from github:BurntSushi/ripgrep
  • ripgrep v15.2.0 (root, install)
    Download: https://github.com/BurntSushi/ripgrep/releases/download/15.2.0/ripgrep-15.2.0-x86_64-unknown-linux-musl.tar.gz
Note nothing was installed

Each plan entry carries the exact artifact that would be downloaded on a Download: line, and --json reports the same value as download_url. Packages whose artifact is resolved by the native tool at install time — system and cargo — print <resolved by source> instead:

$ baller draft jq --source system --dry-run
Dry run jq v1.7.1-6+deb13u3 from system:apt
  • jq v1.7.1-6+deb13u3 (root, install)
    Download: <resolved by source>
Note nothing was installed

Because the GitHub asset is chosen while the package is fetched, a release with no build for the host platform now fails the dry run with NoMatchingAsset instead of reporting a plan that cannot work — see error-handling.md. -v logs the chosen asset's file name alongside the URL.

If any step of the install fails partway through the plan — a download, a missing binary, a pre_install hook vetoing a later package — the packages this run already installed are rolled back before the error is reported, and a package --force reinstalled goes back to the version it was at. See error-handling.md.

Installation Modes

The draft command follows one of four code paths depending on the package source:

Archive mode (GitHub, Baller Registry): select the asset matching the host platform → download archive → SHA-256 verify → extract → symlink binary → record in DB. A GitHub release with no build for this platform fails with NoMatchingAsset, and an archive that extracts without an executable fails with NoBinaryFound — in both cases nothing is linked and nothing reaches the roster. See error-handling.md.

Chocolatey mode (Chocolatey/NuGet): download .nupkg archive → SHA-512 verify (base64 hash decoded from Chocolatey API) → extract as zip → record in DB. NuGet .nupkg files are treated as zip archives.

System mode (PackageSource::System, i.e. apt / dnf / pacman): the package is installed in place by the native package manager under sudo. No archive is downloaded, no extraction happens, no symlink is created — BALLER only records the package in its database for tracking. The pre-install and post-install hooks still run.

Cargo mode (PackageSource::Cargo): the crate is compiled and installed by cargo install into ~/.cargo/bin — without sudo, since the install is user-local. As with system mode, nothing is downloaded, extracted, or symlinked by BALLER; it records the package for tracking and still runs the pre-install and post-install hooks.

Example — archive mode:

$ baller draft ripgrep
Drafting ripgrep...
  Downloading ripgrep [=============>] 2.1 MB / 2.1 MB (5s)
  Linked to ~/.local/bin/rg
Done ripgrep v14.1.0 drafted!

Example — Chocolatey mode:

$ baller draft python
Drafting python...
  Downloading python [=============>] 2.9 kB / 2.9 kB (1s)
  SHA-512 verified
Done python v3.15.0-b3 drafted!

Example — system mode:

$ baller draft default-jdk
Drafting default-jdk...
  System installing via apt...
[sudo] password for user:
Done default-jdk v2:1.21-76 installed via apt!

What happens:

  1. Fetch package metadata from registry chain
  2. Resolve all transitive dependencies
  3. For each dependency (in order): pre-install hook →
    • System source: sudo <pm> install -y <name> → DB insert → post-install hook
    • Archive source: download → hash verify → extract → symlink → DB insert → post-install hook
    • Chocolatey source: download .nupkg → SHA-512 base64 verify → extract as zip → DB insert → post-install hook
  4. Install root package last

eject — Uninstall a Package

baller eject <package_name> [-f] [--purge] [--no-orphans] [--keep-bin]

Removes a package's binary symlink, runs hooks, cleans the cache directory, deletes its database record, and removes any orphaned dependencies.

When ejecting a package, BALLER checks for orphaned dependencies — packages installed as transitive dependencies that are no longer required by any other installed package. Orphans are automatically removed.

The cache directory (~/.baller/cache/<package>-<version>) is cleaned after the database entry is removed.

The post-eject hook runs once the package is fully removed (link, database record, cache directory and, with --purge, the archive). If it fails, the failure is printed as a warning and the eject still succeeds.

Flags:

Flag Description
--force, -f Eject even when the package is frozen
--purge Also delete the cached download archive, not just the extracted directory
--no-orphans Leave orphaned dependencies installed
--keep-bin Drop the roster entry but leave the linked binary in place

Example:

$ baller eject ripgrep
Are you sure you want to eject ripgrep? [y/N] y
Removing unused dependency regex-automata...
Ejected ripgrep

$ baller eject --yes ripgrep
Ejected ripgrep

Frozen packages cannot be ejected — thaw them first with freeze, or pass --force. If the package is not installed, a PackageNotFound error is returned.


roster — List or Search Packages

baller roster [package_name] [--frozen] [--source <S>] [--outdated] [--remote]

Flags:

Flag Description
--frozen Only show frozen packages
--source <S> Only show packages installed from github, baller, chocolatey, system or cargo
--outdated Check the registries and list packages with a newer version available, without updating
--remote Skip the local roster and search registries directly (needs a search term)
--verbose, -v (global) Print the full detail block for every listed package
--json (global) Emit the roster, detail view, outdated report or search results as JSON

Without arguments: Lists all installed packages with versions. Descriptions are safely truncated — no multi-byte character panics.

$ baller roster

Active Roster (2 players):
────────────────────────────
  • ripgrep v14.1.0
    Blazingly fast search tool
  • fd v8.7.0 ❄️
    Simple, fast alternative to find
────────────────────────────

With a package name: Shows detailed info for a locally installed package, or falls back to searching remote registries. Remote search results include descriptions when available. The '<name>' not found locally, searching registries... notice is progress output: it goes to stderr and is hidden by -q and --json, so --json prints only the search document. Only a package that is absent from the roster falls back to the search; if the roster itself cannot be read, that error is reported instead.

$ baller roster ripgrep

Roster - ripgrep
  Version:    14.1.0
  Source:     github
  Source Detail: BurntSushi/ripgrep
  Description: Blazingly fast search tool
  Frozen:     no
  Install Path: ~/.baller/cache/ripgrep-14.1.0
  Binary:     ~/.baller/cache/ripgrep-14.1.0/rg

freeze — Toggle Freeze State

baller freeze [package_name] [--freeze | --thaw] [--all] [--list]

Toggles the frozen flag on a package. Frozen packages cannot be updated or ejected.

Flags:

Flag Description
--freeze Freeze explicitly instead of toggling — a no-op on an already frozen package
--thaw Thaw explicitly instead of toggling. Conflicts with --freeze
--all Apply to every installed package. Requires --freeze or --thaw, since toggling everything is ambiguous
--list Print the frozen packages and exit

The package name is optional when --all or --list is given, and required otherwise.

Example:

$ baller freeze fd
Frozen fd

$ baller freeze fd
Thawed fd (unfrozen)

$ baller freeze fd --freeze
Frozen fd

$ baller freeze fd --freeze
Note fd is already frozen

$ baller freeze --all --thaw
Thawed fd thawed (unfrozen)
Done 1 package(s) thawed

$ baller freeze --list
Empty No frozen packages

substitute — Swap Packages

baller substitute <old_package> <new_package> [--keep-old] [--dry-run] [--no-deps]

Installs the new package (including all resolved dependencies), then removes the old one. If the old package is not in the roster, it is skipped with a warning. Hooks run for both the install (pre-install / post-install for each resolved package) and the removal (post-eject for the old package).

Substitute prompts for confirmation by default, like eject and sweep. Pass the global --yes/-y to skip the prompt.

Flags:

Flag Description
--keep-old Install the new package but leave the old one on the roster. Also lifts the frozen check, since nothing is removed
--dry-run List what would be installed and ejected, then stop
--no-deps Install the new root package alone

If the replacement extracts without an executable, the substitution fails with NoBinaryFound before the old package is ejected, so a broken replacement cannot cost you a working package.

Any failure before the old package is off the roster rolls the whole replacement back: packages it installed fresh are removed, and dependencies you already had (which substitute re-fetches) go back to the version they were at. If the old package's roster entry cannot be removed, its link is put back too, so it comes out of a failed substitution exactly as it went in.

Example:

$ baller substitute ripgrep hound
Are you sure you want to substitute ripgrep with hound? [y/N] y
Substituting ripgrep with hound...
  ... (download, install hound) ...
  ... (eject ripgrep) ...
Done Substitution complete: ripgrep -> hound

$ baller substitute ripgrep hound --dry-run
Dry run substitute ripgrep with hound v0.3.0
  • install hound v0.3.0
  • eject ripgrep
Note nothing was changed

sweep — Clean Cache

baller sweep [--all] [--dry-run] [--threshold <SIZE>]

Sweep is archives-only by default. It deletes the downloaded archive files in ~/.baller/cache/ and leaves the extracted <name>-<version> directories alone — those hold the binaries that installed packages are linked against. Pass --all for the old full-wipe behavior.

Shows the size in human-readable format (e.g. 45.2 MB) before prompting.

Flags:

Flag Description
--all (alias --purge-extracted) Also delete extracted packages — the pre-existing full wipe. This breaks installed binaries until they are re-drafted
--dry-run List the archives (and, with --all, the directories) that would be removed
--threshold <SIZE> Only sweep when the cache exceeds this size. Accepts 50MB, 1.5gb, 512k or a bare byte count
--yes, -y (global) Skip the confirmation prompt

Example:

$ baller sweep --dry-run
Sweeping would remove 3 archive(s) (45.2 MB)
  • ~/.baller/cache/https___github.com_..._ripgrep.zip
  ...

$ baller sweep
Are you sure you want to clear 45.2 MB of cached archives? [y/N] y
Done Cleared 3 archive(s) (45.2 MB)
Note kept 2 extracted package(s) — pass --all to remove them too

$ baller sweep --threshold 100MB
Sweeping cache is 45.2 MB, below the 100.0 MB threshold — nothing swept

$ baller sweep --all --yes
Done Cleared 3 archive(s) and 2 extracted package(s) (61.7 MB)

update — Update All Non-Frozen Packages

baller update [packages...] [--check] [--include-frozen]

Flags:

Flag Description
[packages...] Update only the named packages. No arguments updates everything. An unknown name is a PackageNotFound error
--check (alias --dry-run) Report which packages are stale without updating them
--include-frozen Update frozen packages too, instead of skipping them
--json (global) Emit the updated / stale / up-to-date / failed lists as JSON

Iterates all installed packages, skips frozen ones, checks the registry for newer versions, and upgrades each one. Version comparison uses parse_version_flexible() which handles Debian epoch prefixes, revision suffixes, embedded tags, date-based versions, and multi-segment versions — not just strict semver. Falls back to string comparison when both versions cannot be parsed.

New dependencies introduced by the updated version are automatically installed. The old version's extracted cache directory is pruned only once the new version is linked and recorded. If anything fails before that — a new dependency, the pre_update hook, the new download — the new dependencies are rolled back and the old version keeps its link, roster entry and files, and update stops with the error.

Both BALLER_OLD_VERSION and BALLER_NEW_VERSION environment variables are available in pre-update and post-update hooks.

Example:

$ baller update
OK ripgrep is up-to-date
Fetching new dependency: libz-sys
Updating fd: v8.7.0 -> v8.8.0
  Downloading fd [===========>] ...
Done Update complete: 1 updated, 0 failed

$ baller update fd --check
Stale fd: 8.7.0 -> 8.8.0
Done 1 package(s) can be updated — run baller update to apply

build — Assemble from a Manifest

baller build <path> [--dry-run] [--no-deps] [--install-dir <DIR>] [-f] [--source <S>]

Assembles a package from a local manifest instead of resolving a name through the registry chain. <path> is either a manifest file or a directory — a directory resolves baller.toml first, then baller.json. A directory that holds no manifest but does hold a Cargo.toml is compiled from source instead; see Build a Rust project from source.

Flags:

Flag Description
--dry-run Parse and validate the manifest, resolve a missing download_url, run Referee's advisory gate, print the plan (including any block it would hit), and stop before any download. A manifest without download_url therefore makes a registry call and an advisory call
--no-deps Ignore the manifest's declared dependencies, so none are recorded
--install-dir <DIR> Link the binary into this directory instead of the platform default
--force, -f Build over a package that is already on the roster (otherwise that is an error)
--source <S> Override the manifest's source (including any [source.<os>] table) before resolving. Clears any manifest download_url so the new source is actually consulted. github needs a github.com repository URL in the manifest; system is Linux-only; chocolatey is Windows-only; cargo needs a cargo toolchain on PATH

Both manifest layouts parse: the flat form and the nested form documented in docs/manifest.md.

The pipeline mirrors draft:

  1. Resolve and parse the manifest (selecting the host's [source.<os>] table, if any), then validate that name and version are present.
  2. Apply --source if given, then check that the effective source can serve this host and that the host's CPU is in architectures, if declared. A mismatch fails here, before --dry-run reports a plan, before any hook runs and before anything is fetched.
  3. Fill in a missing download_url from the manifest's source (GitHub, Chocolatey, Baller registry; system and cargo sources need none). The registry's version replaces the manifest's when they differ.
  4. Run Referee's advisory gate on this one package — build does no dependency resolution, so its recorded dependencies are not checked — then the --force check, then the pre_install hook. A blocked package never runs a hook.
  5. Resolve the package source and install from it:
    • download_url present → download it directly.
    • GitHub source → fetch the latest release to fill in the download URL (and the resolved version, which is printed when it differs from the manifest).
    • Chocolatey source → resolve the .nupkg from the manifest's feed_url (Windows only).
    • Baller registry source → resolve from the manifest's registry url.
    • System source → install via the native package manager (Linux only).
  6. Verify the checksum when the manifest carries one, extract the archive, run Referee's artifact scan, and locate the binary. A scan block purges the download; an archive that extracts without an executable fails with NoBinaryFound, and a binary built for another platform (a PE .exe on Linux) fails with PlatformMismatch. Either way nothing is linked and nothing is on the roster.
  7. Link the binary (symlink on Linux, .exe copy on Windows).
  8. Record the package in the database with manifest_path set and user_installed = true, then run the post_install hook.
$ baller build ./mytool
Building C:\dev\mytool\baller.toml...
Scouting latest release of owner/mytool...
Version 1.2.0 -> 1.3.0
  Downloading mytool-x86_64.zip [===========>] ...
Linked symlinked to C:\Users\me\AppData\Local\baller\cache\mytool-1.3.0\mytool.exe
Done mytool v1.3.0 built!

Manifest dependencies are recorded in the database but are not installed by build; draft them separately.

Errors are explicit: manifest not found, no baller.toml/baller.json in the directory, missing required fields, an unknown source type, no resolvable download URL, a checksum mismatch, or an existing installation without --force.

Build a Rust project from source

When <path> is a directory with no baller.toml/baller.json but with a Cargo.toml, build compiles the crate and installs the binary it produces:

  1. Read package.name, package.version (defaults to 0.0.0) and the first [[bin]] name (defaults to the package name) out of Cargo.toml.
  2. Run Referee's advisory gate on the crate's crates.io identity, so a known-vulnerable crate is refused before any compile time is spent (a dry run prints the block instead). An unpublished crate has no advisories.
  3. Run cargo build --release in the project directory.
  4. Locate the artifact in target/release (the bin name, then the same name with - swapped for _, plus .exe on Windows).
  5. Scan that one binary with Referee's Phase B rules — not the whole target/release tree, whose tens of thousands of build files would exhaust the scan budget. A block leaves the binary where cargo put it and links nothing.
  6. Link it into the platform default bin directory — ~/.local/bin on Linux, %LOCALAPPDATA%\baller\bin on Windows — or into --install-dir.
  7. Record the package with source = cargo, manifest_path set to the Cargo.toml and user_installed = true, then run the post_install hook.
$ baller build ./mytool
Building /home/me/dev/mytool/Cargo.toml...
Compiling cargo build --release...
Linked symlinked to /home/me/dev/mytool/target/release/mytool
Done mytool v1.3.0 built!

Dependencies are resolved by cargo while compiling, so none are recorded and --no-deps does not apply; --source does not apply either, because the sources are the ones on disk. Both are rejected with an explicit error. --dry-run, --force, --install-dir, --json and --quiet all behave as they do for a manifest build.

Only single-crate projects are supported — a workspace root (a Cargo.toml with no [package] name) is an error, and so is a build that leaves no matching binary in target/release.


inject — Add a Custom Command

baller inject <path-to-.ball-file>

Parses a .ball manifest and registers the binary it names as a baller subcommand, stored in injected_commands.json under baller's config directory (~/.baller on Linux, %LOCALAPPDATA%\baller on Windows). Afterwards baller <command-name> runs that binary, forwarding every argument and the child's exit code.

Injection is gated behind three separate confirmations, because the injected binary later runs with the user's privileges. Answering anything but y/yes at any prompt aborts without writing.

Before writing, inject rejects manifests that name a built-in command (draft, eject, freeze, roster, substitute, sweep, update, build, inject, help, version), name a binary that does not exist, or whose command name contains whitespace. The stored path is canonicalized, so a relative PATH keeps working from any directory.

At invocation time, REQUIRE-ROOT is enforced (running unprivileged is an error) and every entry in DEPENDS must resolve on PATH.

.ball File Format

[SECTION] headers with KEY = VALUE entries. [COMMAND-NAME] and [PATH] are required; everything else is optional, and VERSION defaults to 0.1.0. Values may be quoted or bare, #/; start a comment, and FLAGS-LIST / DEPENDS are comma-separated.

[COMMAND-NAME]
COMMAND-NAME = "my-tool"

[DESCRIPTION]
DESCRIPTION = "A helpful tool that does X"

[VERSION]
VERSION = "1.0.0"

[FLAGS]
FLAGS-LIST = "-y, --yes, -n, --no"

[AUTHOR]
AUTHOR = "HMythical"

[REQUIRE-ROOT]
ROOTPERMS = false

[DEPENDS]
DEPENDS = "python3, ffmpeg"

[PATH]
PATH = /usr/local/bin/my-tool

FLAGS-LIST and AUTHOR are shown in help output only; baller does not validate the flags a binary actually accepts. See example.ball in the repo root for a working file.

$ baller inject ./my-tool.ball
This will modify baller's runtime behavior by adding a new command. Continue? [yes/no] yes
Only inject .ball files from sources you trust: the binary they name runs with your privileges. Continue? [yes/no] yes
Final confirmation: inject 'my-tool' from /usr/local/bin/my-tool? [yes/no] yes
Done Injected 'my-tool' -> /usr/local/bin/my-tool
Run it with: baller my-tool

Under --json, inject needs --yes (its prompts are never shown) and reports {"command": "inject", "name": …, "binary": …} on success.


referee — Audit the Roster for Vulnerabilities

baller referee [package_name] [--refresh] [--no-scan]          # ≡ audit
baller referee audit  [package...] [--refresh] [--no-scan]
                      [--fail-on block|warn] [--format json|markdown|sarif] [--out FILE]
baller referee check  [package...] [--refresh] [--fail-on block|warn]
baller referee scan   [package...] [--fail-on block|warn]
baller referee cache  [--status | --clear | --prune <DAYS> [--include-vulnerable]]
baller referee config
baller referee sbom   [--out FILE] [--format cyclonedx-json]

A command group over the Referee security layer. With no subcommand it audits, exactly as it always has: every installed package (or the one named) is re-checked against public vulnerability data and its extracted artifact is re-scanned. A package name and a subcommand cannot be mixed — baller referee fd audits fd; baller referee audit fd says the same thing explicitly.

Subcommand What it does
audit Advisory check (Phase A) and artifact re-scan (Phase B). The default
check Advisory data only — the same path as audit --no-scan; no extracted tree is walked
scan Artifact re-scan only — no advisory lookup. A swept extract directory reports artifact not on disk — nothing to re-scan, distinct from a clean scan
cache Verdict-cache management: --status (the default) shows rows per ecosystem, the newest checked_at and how many clean verdicts cache_ttl_days has aged out (stale in --json); --clear empties the cache; --prune <DAYS> drops verdicts older than DAYS days except vulnerable ones, and reports how many vulnerable verdicts it kept; --include-vulnerable (only with --prune) drops those too and reports how many went. --status, --clear and --prune are mutually exclusive
config Prints the [referee] settings in effect. enabled accounts for --no-referee; cache_ttl_days shows off when unset; the VirusTotal key is shown only as set/unset
sbom Writes a CycloneDX 1.5 JSON inventory of the roster to stdout or --out

Flags:

Flag Applies to Description
--refresh bare, audit, check Drop cached verdicts and re-query the advisory service. A clean verdict recorded earlier was computed against the advisory data of that day
--no-scan bare, audit Check advisory data only; skip the artifact re-scan
--fail-on block|warn audit, check, scan Exit 1 when any package reaches the level through an advisory (banded at or above block_at/warn_at) or a re-scan finding (block: a block-severity finding; warn: any finding). warn includes everything block catches. check never scans, so only advisories count there; scan has no advisories, so only findings count. Only the exit code changes — nothing is ejected or updated
--format json|markdown|sarif audit Render the report in this format. Without --out it replaces the table on stdout
--out FILE audit, sbom Write the formatted report (or SBOM) to FILE. On audit it requires --format, and stdout keeps the normal table or --json output
--format cyclonedx-json sbom The SBOM format (the default and only one)

Every subcommand is read-only with respect to the roster; cache writes only to the verdict cache. audit, check and scan refuse to run when Referee is disabled; cache, config and sbom work either way.

$ baller referee --refresh
Refereeing 2 package(s) — warn at 2.50, block at 4.00 on the 0-5 risk scale
PACKAGE                  VERSION        STATUS       RISK     ADVISORIES
alpha                    1.0.0          vulnerable   4.90     GHSA-late
    • GHSA-late (CVE-2026-4242) CVSS 9.8 — a serious flaw in alpha
beta                     2.0.0          clean        —        —

Summary 2 package(s): 1 over the block threshold, 0 warned, 0 not verified
Note the audit changes nothing — eject or update a flagged package yourself

$ baller referee check --fail-on block -q
...
[Error]: referee found 1 package(s) at or above the 'block' band (--fail-on block): alpha v1.0.0
$ echo $?
1

Referee also runs automatically inside draft, update, substitute and build (one package — build resolves no dependencies). eject is not gated: it installs nothing. referee.md documents the phases, the risk index, the scan rules, the SARIF and SBOM output and the [referee] config section.


help — List Commands or Describe One

baller help [command]

With no argument, prints every built-in command followed by an Injected commands: section listing whatever inject has registered — which is why baller ships its own help rather than clap's built-in one, since clap only knows about compile-time subcommands.

With an argument, prints the usage, arguments, and notes for that one command. Built-in names resolve first, then injected ones; an unrecognized name is an error. For an injected command the detail view shows its version, author, flags, dependencies, root requirement, and the binary it points at.

baller --help and -h still print clap's own summary (stdout, exit 0) and point at baller help for the injected list. Combined with --json they are answered by help instead: baller --json --help is baller --json help, and baller --json eject -h is baller --json help eject (a referee subcommand's -h describes referee).

With --json the overview lists commands (name, summary, usage), injected (name, description, version) and global_options (name, description). A built-in's detail carries topic, kind: "builtin", summary, usage, arguments and subcommands (each name/description) and notes; an injected command's carries kind: "injected" and every field of its .ball manifest. An unknown name is a JSON error.

$ baller --json help eject
{
  "command": "help",
  "topic": "eject",
  "kind": "builtin",
  "summary": "Ejects (Uninstalls) a player from your team",
  "usage": "baller eject <PACKAGE_NAME>",
  "arguments": [
    { "name": "<PACKAGE_NAME>", "description": "Package to uninstall" },
    { "name": "-f, --force", "description": "Eject even when the package is frozen" },
    …
  ],
  "subcommands": [],
  "notes": ["Frozen packages must be unfrozen before they can be ejected."]
}
$ baller help roster
roster - Rosters (Lists) active players on your team or searches for one

Usage: baller roster [PACKAGE_NAME]

  [PACKAGE_NAME]  Package to look up; omit to list everything installed

version — Print the Version

baller version

Prints Baller <version>. baller -V/--version is clap's own form of the same request (baller <version>). With --json, all three print {"command": "version", "version": "<version>"}. --quiet does not hide it: like every command's result, the version is data, not progress.


Confirmation Prompts

Destructive commands (eject, sweep, substitute) prompt for confirmation unless the global --yes / -y flag is passed:

$ baller eject myapp
Are you sure you want to eject myapp? [y/N] y
Ejected myapp

$ baller eject --yes myapp
Ejected myapp

The prompt is written to stderr, so it never mixes into output piped from stdout. Under --json nothing is prompted: the command fails with a ConfirmationRequired JSON error and changes nothing, and --yes is required.

$ baller --json eject myapp
{
  "command": "eject",
  "error": "confirmation required: Are you sure you want to eject myapp? — pass --yes/-y to proceed under --json",
  "code": "ConfirmationRequired"
}