refactor: get rid of KERI implementation details from CLI layer

crates/auths-cli/src/commands/artifact/mod.rs

@@ -181,16 +181,16 @@ pub enum ArtifactSubcommand {
         #[arg(long, value_parser)]
         identity_bundle: Option<PathBuf>,
 
-        /// Path to witness receipts JSON file.
-        #[arg(long)]
+        /// Path to witness signatures JSON file.
+        #[arg(long = "witness-signatures")]
         witness_receipts: Option<PathBuf>,
 
         /// Witness public keys as DID:hex pairs (e.g., "did:key:z6Mk...:abcd1234...").
         #[arg(long, num_args = 1..)]
         witness_keys: Vec<String>,
 
-        /// Witness quorum threshold (default: 1).
-        #[arg(long, default_value = "1")]
+        /// Number of witnesses required (default: 1).
+        #[arg(long = "witnesses-required", default_value = "1")]
         witness_threshold: usize,
 
         /// Also verify the source commit's signing attestation.

crates/auths-cli/src/commands/cache.rs

@@ -9,7 +9,7 @@ use auths_sdk::core_config::EnvironmentConfig;
 use auths_sdk::keri::cache;
 
 #[derive(Parser, Debug, Clone)]
-#[command(about = "Manage local identity history cache")]
+#[command(about = "Manage cached identity snapshots")]
 pub struct CacheCommand {
     #[command(subcommand)]
     command: CacheSubcommand,
@@ -47,15 +47,15 @@ fn handle_list(auths_home: &std::path::Path) -> Result<()> {
     let entries = cache::list_cached_entries(auths_home)?;
 
     if entries.is_empty() {
-        println!("No cached identity states found.");
+        println!("No cached snapshots found.");
         return Ok(());
     }
 
-    println!("Cached identity states:\n");
+    println!("Cached identity snapshots:\n");
     for entry in entries {
         println!("  Identity ID: {}", entry.did);
         println!("  Sequence: {}", entry.sequence);
-        println!("  Validated against: {}", entry.validated_against_tip_said);
+        println!("  Verified against: {}", entry.validated_against_tip_said);
         println!("  Commit OID: {}", entry.last_commit_oid);
         println!("  Cached at: {}", entry.cached_at);
         println!("  File: {}", entry.path.display());
@@ -73,15 +73,17 @@ fn handle_inspect(auths_home: &std::path::Path, did: &str) -> Result<()> {
             println!("Identity ID: {}", cached.did);
             println!("Sequence: {}", cached.sequence);
             println!(
-                "Validated against tip: {}",
+                "Verified against log entry: {}",
                 cached.validated_against_tip_said
             );
             println!("Last commit OID: {}", cached.last_commit_oid);
             println!("Cached at: {}", cached.cached_at);
             println!("\nKey State:");
-            println!("  Prefix: {}", cached.state.prefix);
             println!("  Current keys: {:?}", cached.state.current_keys);
-            println!("  Next commitment: {:?}", cached.state.next_commitment);
+            println!(
+                "  Pre-committed rotation key: {:?}",
+                cached.state.next_commitment
+            );
             println!("  Is abandoned: {}", cached.state.is_abandoned);
             println!(
                 "\nCache file: {}",

crates/auths-cli/src/commands/ci/rotate.rs

@@ -189,7 +189,7 @@ pub fn run_rotate(
         super::setup::humanize_duration(max_age_secs)
     );
     println!(
-        "To revoke: auths device revoke --device-did {} --key {}",
+        "To revoke: auths device revoke --device {} --key {}",
         device_did, identity_key_alias
     );
 

crates/auths-cli/src/commands/ci/setup.rs

@@ -252,7 +252,7 @@ pub fn run_setup(
     );
     println!("To rotate: auths ci rotate");
     println!(
-        "To revoke: auths device revoke --device-did {} --key {}",
+        "To revoke: auths device revoke --device {} --key {}",
         device_did, identity_key_alias
     );
 

crates/auths-cli/src/commands/device/authorization.rs

@@ -38,18 +38,17 @@ struct DeviceEntry {
 
 #[derive(Args, Debug, Clone)]
 #[command(
-    about = "Manage device authorizations within an identity repository.",
+    about = "Manage which devices can sign with your identity.",
     after_help = "Examples:
-  auths device list         # List all linked devices
-  auths device link --key identity-key --device-key device-key --device-did did:key:...
-                            # Link a new device to your identity
-  auths device revoke       # Revoke a device authorization
+  auths device list         # List authorized devices
+  auths device link --key identity-key --device-key device-key --device did:key:...
+                            # Authorize a new device
+  auths device revoke       # Revoke a device
   auths device extend       # Extend device expiry
 
 Related:
-  auths pair    — Pair a new device with your identity
   auths status  — Show device status and expiry
-  auths init    — Set up identity and linking"
+  auths init    — Set up identity and signing"
 )]
 pub struct DeviceCommand {
     #[command(subcommand)]
@@ -74,19 +73,19 @@ pub enum DeviceSubcommand {
     /// Authorize a new device to act on behalf of the identity.
     #[command(visible_alias = "add")]
     Link {
-        #[arg(long, help = "Local alias of the *identity's* key (used for signing).")]
+        #[arg(long, help = "Your identity's key name.")]
         key: String,
 
         #[arg(
             long,
-            help = "Local alias of the *new device's* key (must be imported first)."
+            help = "The new device's key name (import first with: auths key import)."
         )]
         device_key: String,
 
         #[arg(
             long,
             visible_alias = "device",
-            help = "Identity ID of the new device being authorized (must match --device-key)."
+            help = "The device's ID (must match --device-key)."
         )]
         device_did: String,
 
@@ -128,17 +127,10 @@ pub enum DeviceSubcommand {
 
     /// Revoke an existing device authorization using the identity key.
     Revoke {
-        #[arg(
-            long,
-            visible_alias = "device",
-            help = "Identity ID of the device authorization to revoke."
-        )]
+        #[arg(long, visible_alias = "device", help = "The device's ID to revoke.")]
         device_did: String,
 
-        #[arg(
-            long,
-            help = "Local alias of the *identity's* key (required to authorize revocation)."
-        )]
+        #[arg(long, help = "Your identity's key name.")]
         key: String,
 
         #[arg(long, help = "Optional note explaining the revocation.")]
@@ -148,12 +140,12 @@ pub enum DeviceSubcommand {
         dry_run: bool,
     },
 
-    /// Resolve a device DID to its controller identity DID.
+    /// Resolve a device to its owner identity.
     Resolve {
         #[arg(
             long,
             visible_alias = "device",
-            help = "The device DID to resolve (e.g. did:key:z6Mk...)."
+            help = "The device ID to resolve (e.g. did:key:z6Mk...)."
         )]
         device_did: String,
     },
@@ -167,11 +159,7 @@ pub enum DeviceSubcommand {
 
     /// Extend the expiration date of an existing device authorization.
     Extend {
-        #[arg(
-            long,
-            visible_alias = "device",
-            help = "Identity ID of the device authorization to extend."
-        )]
+        #[arg(long, visible_alias = "device", help = "The device's ID to extend.")]
         device_did: String,
 
         /// Duration in seconds until expiration (per RFC 6749).
@@ -182,16 +170,10 @@ pub enum DeviceSubcommand {
         )]
         expires_in: u64,
 
-        #[arg(
-            long,
-            help = "Local alias of the *identity's* key (required for re-signing)."
-        )]
+        #[arg(long, help = "Your identity's key name.")]
         key: String,
 
-        #[arg(
-            long,
-            help = "Local alias of the *device's* key (required for re-signing)."
-        )]
+        #[arg(long, help = "The device's key name.")]
         device_key: String,
     },
 }
@@ -331,11 +313,11 @@ pub fn handle_device(
 
 fn display_link_result(
     result: &auths_sdk::result::DeviceLinkResult,
-    device_did: &str,
+    _device_did: &str,
 ) -> Result<()> {
     println!(
-        "\n✅ Successfully linked device {} (attestation: {})",
-        device_did, result.attestation_id
+        "\n✅ Device authorized. (Attestation: {})",
+        result.attestation_id
     );
     Ok(())
 }
@@ -577,7 +559,7 @@ fn list_devices(
         .map_err(anyhow::Error::from);
     }
 
-    println!("Devices for identity: {}", identity.controller_did);
+    println!("Authorized devices for: {}", identity.controller_did);
     if entries.is_empty() {
         if include_revoked {
             println!("  No authorized devices found.");

crates/auths-cli/src/commands/device/pair/common.rs

@@ -323,7 +323,7 @@ pub(crate) fn handle_pairing_response(
             println!("  You can manually link this device using:");
             println!(
                 "    {}",
-                style(format!("auths device link --device-did {} ...", device_did)).dim()
+                style(format!("auths device link --device {} ...", device_did)).dim()
             );
             save_device_info(now, auths_dir, &response)?;
         }

crates/auths-cli/src/commands/device/pair/online.rs

@@ -142,7 +142,7 @@ pub(crate) async fn handle_initiate_online(
             println!("  You can manually link this device using:");
             println!(
                 "    {}",
-                style(format!("auths device link --device-did {} ...", device_did)).dim()
+                style(format!("auths device link --device {} ...", device_did)).dim()
             );
         }
     }

crates/auths-cli/src/commands/device/verify_attestation.rs

@@ -32,18 +32,18 @@ pub struct VerifyCommand {
     #[arg(long, value_parser, required = true)]
     pub attestation: String,
 
-    /// Issuer public key in hex format (64 hex chars = 32 bytes).
+    /// Signer public key in hex format (64 hex chars = 32 bytes).
     ///
     /// If provided, bypasses trust resolution and uses this key directly.
-    /// Takes precedence over --issuer-did and trust policy.
-    #[arg(long = "issuer-pk", value_parser)]
+    /// Takes precedence over --signer and trust policy.
+    #[arg(long = "signer-key", value_parser)]
     pub issuer_pk: Option<String>,
 
-    /// Issuer identity ID for trust-based key resolution.
+    /// Signer identity ID for trust-based key resolution.
     ///
     /// Looks up the public key from pinned identity store or roots.json.
     /// Uses --trust policy to determine behavior for unknown identities.
-    #[arg(long = "issuer-did", visible_alias = "issuer", value_parser)]
+    #[arg(long = "signer", visible_alias = "issuer-did", value_parser)]
     pub issuer_did: Option<String>,
 
     /// Trust policy for unknown identities.
@@ -68,12 +68,12 @@ pub struct VerifyCommand {
     #[arg(long = "require-capability")]
     pub require_capability: Option<String>,
 
-    /// Path to witness receipts JSON file.
-    #[arg(long)]
+    /// Path to witness signatures JSON file.
+    #[arg(long = "witness-signatures")]
     pub witness_receipts: Option<PathBuf>,
 
-    /// Witness quorum threshold (default: 1).
-    #[arg(long, default_value = "1")]
+    /// Number of witnesses required (default: 1).
+    #[arg(long = "witnesses-required", default_value = "1")]
     pub witness_threshold: usize,
 
     /// Witness public keys as DID:hex pairs (e.g., "did:key:z6Mk...:abcd1234...").
@@ -243,7 +243,7 @@ fn resolve_issuer_key(
             // The attestation itself doesn't contain the issuer's public key directly,
             // so we need it from --issuer-pk or the user needs to provide it
             anyhow::bail!(
-                "Unknown identity '{}'. Provide --issuer-pk to trust on first use, \
+                "Unknown identity '{}'. Provide --signer-key to trust on first use, \
                  or add to .auths/roots.json for explicit trust.",
                 did
             );
@@ -254,7 +254,7 @@ fn resolve_issuer_key(
                  Options:\n  \
                  1. Add to .auths/roots.json in the repository\n  \
                  2. Pin manually: auths trust pin --did {} --key <hex>\n  \
-                 3. Provide --issuer-pk <hex> to bypass trust resolution",
+                 3. Provide --signer-key <hex> to bypass trust resolution",
                 did,
                 did
             );

crates/auths-cli/src/commands/emergency.rs

@@ -47,7 +47,7 @@ pub enum EmergencySubcommand {
 /// Revoke a compromised device.
 #[derive(Parser, Debug, Clone)]
 pub struct RevokeDeviceCommand {
-    /// Device DID to revoke.
+    /// Device ID to revoke.
     #[arg(long)]
     pub device: Option<String>,
 
@@ -306,7 +306,7 @@ fn handle_revoke_device(
         did
     } else if std::io::stdin().is_terminal() {
         Input::new()
-            .with_prompt("Enter device DID to revoke")
+            .with_prompt("Enter device ID to revoke")
             .interact_text()?
     } else {
         return Err(anyhow!("--device is required in non-interactive mode"));
@@ -426,7 +426,7 @@ fn handle_rotate_now(
         out.print_info("Dry run mode - no changes will be made");
         out.newline();
         out.println("Would perform the following actions:");
-        out.println("  1. Generate new Ed25519 keypair");
+        out.println("  1. Generate new signing key");
         out.println("  2. Create rotation event in identity log");
         out.println("  3. Update key alias mappings");
         return Ok(());