auths_cli/errors/
cli_error.rs

1//! Typed CLI error variants with actionable help text.
2
3/// Structured CLI errors with built-in suggestion and documentation links.
4#[derive(thiserror::Error, Debug)]
5pub enum CliError {
6    #[error("key rotation failed — no pre-rotation commitment found")]
7    NoPrerotationCommitment,
8
9    #[error("identity not found — run `auths init` to create one")]
10    IdentityNotFound,
11
12    #[error("keychain unavailable — set AUTHS_KEYCHAIN_BACKEND=file for headless environments")]
13    KeychainUnavailable,
14
15    #[error("device key '{alias}' not found — import it first with `auths key import`")]
16    DeviceKeyNotFound { alias: String },
17
18    #[error("passphrase required — set AUTHS_PASSPHRASE env var for CI environments")]
19    PassphraseRequired,
20
21    #[error("attestation expired — issue a new one with `auths device link`")]
22    AttestationExpired,
23
24    #[error("capability '{capability}' not granted — check device authorization policies")]
25    MissingCapability { capability: String },
26}
27
28impl CliError {
29    /// Human-readable suggestion for how to recover from this error.
30    pub fn suggestion(&self) -> &str {
31        match self {
32            Self::NoPrerotationCommitment => {
33                "Run: auths id rotate --next-key-alias <alias-for-next-key>"
34            }
35            Self::IdentityNotFound => "Run: auths init",
36            Self::KeychainUnavailable => {
37                "Set AUTHS_KEYCHAIN_BACKEND=file and AUTHS_PASSPHRASE=<passphrase> in your environment."
38            }
39            Self::DeviceKeyNotFound { .. } => {
40                "Run: auths key import --key-alias <alias> --seed-file <path>"
41            }
42            Self::PassphraseRequired => {
43                "Set AUTHS_PASSPHRASE=<your-passphrase> in the environment, or run interactively."
44            }
45            Self::AttestationExpired => {
46                "Run: auths device link --key <key> --device-key <device-key> --device-did <did>"
47            }
48            Self::MissingCapability { .. } => {
49                "Re-authorize the device with `auths device link` to grant the capability."
50            }
51        }
52    }
53
54    /// Documentation URL for this error, if available.
55    ///
56    /// Deep links are parked on the docs root until the docs site serves
57    /// per-guide routes — every subpath currently 404s.
58    pub fn docs_url(&self) -> Option<&str> {
59        match self {
60            Self::NoPrerotationCommitment | Self::IdentityNotFound | Self::KeychainUnavailable => {
61                Some("https://docs.auths.dev")
62            }
63            _ => None,
64        }
65    }
66}
auths_cli/errors/cli_error.rs

auths_cli/errors/
cli_error.rs
