ma_core/config/
cli.rs

1//! Command-line argument struct for ma-core-based binaries.
2//!
3//! Flatten [`MaArgs`] into your own `#[derive(Parser)]` struct so that every
4//! binary in the ma ecosystem accepts a consistent set of arguments:
5//!
6//! ```rust,ignore
7//! use clap::Parser;
8//! use ma_core::config::MaArgs;
9//!
10//! const MA_DEFAULT_SLUG: &str = "panteia";
11//!
12//! #[derive(Parser)]
13//! struct Cli {
14//!     #[command(flatten)]
15//!     ma: MaArgs,
16//! }
17//!
18//! fn main() -> anyhow::Result<()> {
19//!     let cli = Cli::parse();
20//!     let config = ma_core::config::Config::from_args(&cli.ma, MA_DEFAULT_SLUG)?;
21//!     config.init_logging()?;
22//!     Ok(())
23//! }
24//! ```
25
26use std::path::PathBuf;
27
28use clap::Args;
29
30/// Standard ma-core CLI arguments.
31///
32/// Add these to your binary with `#[command(flatten)]`.
33///
34/// All fields are resolved from `MA_*` environment variables, a YAML config
35/// file, and built-in defaults — in that priority order.
36#[derive(Args, Debug, Clone, Default)]
37pub struct MaArgs {
38    /// Path to the YAML config file. Overrides the slug-derived default
39    /// (`XDG_CONFIG_HOME/ma/<slug>.yaml`).
40    ///
41    /// Environment variable: `MA_CONFIG`
42    #[arg(long, env = "MA_CONFIG")]
43    pub config: Option<PathBuf>,
44
45    /// Runtime slug. Overrides YAML and `MA_DEFAULT_SLUG` for file naming
46    /// (`<slug>.yaml`, `<slug>.bin`, `<slug>.log`). YAML `slug` cannot choose
47    /// which configuration file is read.
48    ///
49    /// Environment variable: `MA_SLUG`
50    #[arg(long, env = "MA_SLUG")]
51    pub slug: Option<String>,
52
53    /// Log level for the log file (`trace`, `debug`, `info`, `warn`, `error`).
54    ///
55    /// Environment variable: `MA_LOG_LEVEL`. Falls back to YAML → default `"info"`.
56    #[arg(long)]
57    pub log_level: Option<String>,
58
59    /// Path to the log file. Defaults to `XDG_DATA_HOME/ma/<slug>.log`.
60    ///
61    /// Environment variable: `MA_LOG_FILE`. Falls back to YAML → XDG default.
62    #[arg(long)]
63    pub log_file: Option<PathBuf>,
64
65    /// Log level for stdout output (`trace`, `debug`, `info`, `warn`, `error`).
66    ///
67    /// Environment variable: `MA_LOG_LEVEL_STDOUT`. Falls back to YAML → default `"info"`.
68    #[arg(long)]
69    pub log_level_stdout: Option<String>,
70
71    /// Positive DID cache TTL in seconds.
72    ///
73    /// Set to `0` to disable caching successful DID resolutions.
74    /// Environment variable: `MA_DID_RESOLVER_POSITIVE_TTL_SECS`. Falls back to YAML → default `60`.
75    #[arg(long)]
76    pub did_resolver_positive_ttl_secs: Option<u64>,
77
78    /// Negative DID cache TTL in seconds.
79    ///
80    /// Set to `0` to disable caching failed DID resolutions.
81    /// Environment variable: `MA_DID_RESOLVER_NEGATIVE_TTL_SECS`. Falls back to YAML → default `10`.
82    #[arg(long)]
83    pub did_resolver_negative_ttl_secs: Option<u64>,
84
85    /// Path to the encrypted secret bundle file.
86    /// Defaults to `XDG_CONFIG_HOME/ma/<slug>.bin`.
87    ///
88    /// Environment variable: `MA_SECRET_BUNDLE`. Falls back to YAML → XDG default.
89    #[arg(long)]
90    pub secret_bundle: Option<PathBuf>,
91
92    /// Passphrase to unlock the secret bundle.
93    ///
94    /// In headless configs this is stored in cleartext in the YAML file.
95    /// Prefer setting via environment variable rather than CLI to avoid
96    /// shell history exposure.
97    ///
98    /// Environment variable: `MA_SECRET_BUNDLE_PASSPHRASE`. Falls back to YAML.
99    #[arg(long)]
100    pub secret_bundle_passphrase: Option<String>,
101
102    /// Kubo RPC API URL. Defaults to `http://127.0.0.1:5001`.
103    ///
104    /// Environment variable: `MA_KUBO_RPC_URL`. Falls back to YAML → default.
105    #[arg(long)]
106    pub kubo_rpc_url: Option<String>,
107
108    /// IPNS key alias used in Kubo. Defaults to the slug.
109    ///
110    /// Environment variable: `MA_KUBO_KEY_ALIAS`. Falls back to YAML → slug.
111    #[arg(long)]
112    pub kubo_key_alias: Option<String>,
113
114    /// Mirror selected CIDs to a configured Kubo remote pinning service.
115    ///
116    /// Environment variable: `MA_PIN_REMOTE`. Falls back to YAML → `false`.
117    #[arg(long, num_args = 0..=1, default_missing_value = "true")]
118    pub pin_remote: Option<bool>,
119
120    /// Kubo remote pinning service name, e.g. `pinata`.
121    ///
122    /// Environment variable: `MA_PIN_REMOTE_SERVICE`. Falls back to YAML.
123    #[arg(long)]
124    pub pin_remote_service: Option<String>,
125
126    /// Operator-visible remote pin name. Callers may supply a default when unset.
127    ///
128    /// Environment variable: `MA_PIN_REMOTE_NAME`. Falls back to YAML.
129    #[arg(long)]
130    pub pin_remote_name: Option<String>,
131
132    /// Replace older pins with the same managed name after a new pin succeeds.
133    ///
134    /// Environment variable: `MA_PIN_OVERWRITE`. Falls back to YAML → `true`.
135    #[arg(long, num_args = 0..=1, default_missing_value = "true")]
136    pub pin_overwrite: Option<bool>,
137
138    /// Generate a headless config with a fresh secret bundle, write both
139    /// files with 0600 permissions, and exit.
140    ///
141    /// If `--secret-bundle-passphrase` is not provided, a random passphrase
142    /// is generated and written into the config file.
143    #[arg(long)]
144    pub gen_headless_config: bool,
145}
ma_core/config/cli.rs

ma_core/config/
cli.rs
