basil_bin/
lib.rs

1// SPDX-FileCopyrightText: 2026 OpenBasil Contributors
2//
3// SPDX-License-Identifier: Apache-2.0
4
5//! Library surface for the unified `basil` binary.
6//!
7//! This crate is primarily a binary (`basil`), but it also exposes its
8//! command-line definition as a library so tooling, notably the `xtask`
9//! man-page generator, can render the command tree without launching the
10//! process. [`cli`] returns the fully assembled clap command.
11
12#![cfg_attr(test, allow(clippy::indexing_slicing))]
13
14pub mod client_cli;
15
16use basil_core::{agent_cli, bundle_cli, init};
17use clap::{CommandFactory, Parser, Subcommand};
18
19/// Top-level `basil` command-line interface.
20#[derive(Debug, Parser)]
21#[command(name = "basil", version, about = "Basil broker and operator tool")]
22pub struct Cli {
23    /// Path to the agent's Unix socket for over-socket commands.
24    #[arg(long, env = "BASIL_SOCKET", global = true)]
25    pub socket: Option<String>,
26
27    #[command(subcommand)]
28    pub command: Command,
29}
30
31/// Top-level `basil` subcommands.
32#[derive(Debug, Subcommand)]
33pub enum Command {
34    /// Scaffold a first-run starter set (config, catalog, policy).
35    Init(Box<init::InitArgs>),
36    /// Run the broker daemon.
37    Agent(agent_cli::RunArgs),
38    /// Create and manage a sealed credential bundle.
39    #[command(subcommand)]
40    Bundle(Box<bundle_cli::BundleCommand>),
41    /// Explain a policy decision: why a subject would be allowed or denied an op
42    /// on a key. By DEFAULT this is an offline dry-run — it builds the PDP from
43    /// the catalog + policy FILES on disk and evaluates the tuple through the same
44    /// matcher enforcement uses (no socket, no backend, no secrets). With `--live`
45    /// it instead queries the RUNNING broker's serving generation over the global
46    /// `--socket` (needs the `explain` admin permission). `--effective` previews
47    /// every grant for the subject and is offline-only.
48    Explain(agent_cli::ExplainArgs),
49    /// Preflight environment and deployment checks.
50    Doctor(agent_cli::DoctorArgs),
51    #[command(flatten)]
52    Client(client_cli::Command),
53}
54
55/// Returns the fully assembled top-level clap [`Command`](clap::Command) for the
56/// `basil` binary, for tooling such as man-page and shell-completion generation.
57#[must_use]
58pub fn cli() -> clap::Command {
59    Cli::command()
60}
61
62#[cfg(test)]
63mod tests {
64    use super::*;
65
66    fn parse(args: &[&str]) -> Cli {
67        Cli::try_parse_from(args).expect("parse cli")
68    }
69
70    #[test]
71    fn bundle_is_top_level_command() {
72        let cli = parse(&[
73            "basil",
74            "bundle",
75            "verify",
76            "creds.sealed",
77            "--open",
78            "passphrase:file=/run/pass",
79        ]);
80        assert!(matches!(cli.command, Command::Bundle(_)));
81    }
82
83    #[test]
84    fn old_config_bundle_path_is_not_user_facing() {
85        let err = Cli::try_parse_from(["basil", "config", "bundle", "verify"])
86            .expect_err("config bundle must not remain as a compatibility command");
87        assert!(
88            err.to_string().contains("unrecognized subcommand")
89                || err.to_string().contains("invalid subcommand"),
90            "{err}"
91        );
92    }
93
94    #[test]
95    fn set_backend_accepts_structured_backend_value() {
96        let cli = parse(&[
97            "basil",
98            "bundle",
99            "set-backend",
100            "creds.sealed",
101            "--backend",
102            "id=aws1,type=aws-kms,region=us-east-1,profile=prod",
103            "--open",
104            "passphrase:file=/run/pass",
105        ]);
106        assert!(matches!(cli.command, Command::Bundle(_)));
107    }
108}
basil_bin/lib.rs

basil_bin/
lib.rs
