localvault 1.1.1 → 1.2.1

data/lib/localvault/cli/team.rb

@@ -1,13 +1,99 @@
 require "thor"
+require "securerandom"
 
 module LocalVault
   class CLI
     class Team < Thor
+      desc "init", "Initialize a vault as a team vault (sets you as owner)"
+      method_option :vault, type: :string, aliases: "-v"
+      # Initialize a vault as a team vault with you as the owner.
+      #
+      # This is the explicit transition from personal sync to team-shared sync.
+      # Creates the owner's key slot and bumps the bundle to v3.
+      def init
+        unless Config.token
+          $stderr.puts "Error: Not logged in."
+          $stderr.puts "\n  localvault login YOUR_TOKEN\n"
+          $stderr.puts "Get your token at: https://inventlist.com/settings"
+          return
+        end
+
+        unless Identity.exists?
+          $stderr.puts "Error: No keypair found. Run: localvault keygen"
+          return
+        end
+
+        vault_name = options[:vault] || Config.default_vault
+        handle = Config.inventlist_handle
+
+        master_key = SessionCache.get(vault_name)
+        unless master_key
+          $stderr.puts "Error: Vault '#{vault_name}' is not unlocked. Run: localvault show -v #{vault_name}"
+          return
+        end
+
+        client = ApiClient.new(token: Config.token)
+        begin
+          blob = client.pull_vault(vault_name)
+          unless blob.is_a?(String) && !blob.empty?
+            $stderr.puts "Error: Vault '#{vault_name}' has not been synced. Run: localvault sync push -v #{vault_name}"
+            return
+          end
+          data = SyncBundle.unpack(blob)
+          if data[:owner]
+            $stderr.puts "Error: Vault '#{vault_name}' is already a team vault. Owner: @#{data[:owner]}"
+            return
+          end
+        rescue ApiClient::ApiError => e
+          if e.status == 404
+            $stderr.puts "Error: Vault '#{vault_name}' has not been synced. Run: localvault sync push -v #{vault_name}"
+          else
+            $stderr.puts "Error: #{e.message}"
+          end
+          return
+        end
+
+        # Create owner key slot
+        pub_b64 = Identity.public_key
+        enc_key = KeySlot.create(master_key, pub_b64)
+        key_slots = {
+          handle => { "pub" => pub_b64, "enc_key" => enc_key, "scopes" => nil, "blob" => nil }
+        }
+
+        # Preserve existing key slots from v2 (upgrade path)
+        data[:key_slots].each do |h, slot|
+          next if h == handle
+          next unless slot.is_a?(Hash) && slot["pub"].is_a?(String)
+          key_slots[h] = slot.merge("scopes" => nil, "blob" => nil)
+        end
+
+        store = Store.new(vault_name)
+        new_blob = SyncBundle.pack_v3(store, owner: handle, key_slots: key_slots)
+        client.push_vault(vault_name, new_blob)
+
+        $stdout.puts "Vault '#{vault_name}' is now a team vault."
+        $stdout.puts "Owner: @#{handle}"
+        $stdout.puts "\nNext: localvault team add @handle -v #{vault_name}"
+      rescue SyncBundle::UnpackError => e
+        $stderr.puts "Error: #{e.message}"
+      end
+
       desc "list [VAULT]", "Show who has access to a vault"
       method_option :vault, type: :string, aliases: "-v"
+      # List all users who have access to a vault.
+      #
+      # Checks sync-based key slots first; falls back to direct shares if no
+      # key slots exist. Displays member handles (key slots) or a share table
+      # with ID, recipient, status, and date.
       def list(vault_name = nil)
         unless Config.token
-          $stderr.puts "Error: Not connected. Run: localvault connect --token TOKEN --handle HANDLE"
+          $stderr.puts "Error: Not logged in."
+          $stderr.puts
+          $stderr.puts "  localvault login YOUR_TOKEN"
+          $stderr.puts
+          $stderr.puts "Get your token at: https://inventlist.com/settings"
+          $stderr.puts "New to InventList? Sign up free at https://inventlist.com"
+          $stderr.puts "Docs: https://inventlist.com/sites/localvault/series/localvault"
           return
         end
 
@@ -43,11 +129,54 @@ module LocalVault
         $stderr.puts "Error: #{e.message}"
       end
 
+      desc "verify HANDLE", "Check if a user exists and has a public key for sharing"
+      # Verify a user's handle and public key status before adding them.
+      #
+      # Checks InventList for the handle and whether they have a published
+      # X25519 public key. Does not modify anything.
+      def verify(handle)
+        unless Config.token
+          $stderr.puts "Error: Not logged in."
+          $stderr.puts "\n  localvault login YOUR_TOKEN\n"
+          $stderr.puts "Get your token at: https://inventlist.com/settings"
+          return
+        end
+
+        handle = handle.delete_prefix("@")
+        client = ApiClient.new(token: Config.token)
+        result = client.get_public_key(handle)
+        pub_key = result["public_key"]
+
+        if pub_key && !pub_key.empty?
+          fingerprint = pub_key.length > 12 ? "#{pub_key[0..7]}...#{pub_key[-4..]}" : pub_key
+          $stdout.puts "@#{handle} — public key published"
+          $stdout.puts "  Fingerprint: #{fingerprint}"
+          $stdout.puts "  Ready for: localvault team add @#{handle} -v VAULT"
+        else
+          $stderr.puts "@#{handle} exists but has no public key published."
+          $stderr.puts "They need to run: localvault login TOKEN"
+        end
+      rescue ApiClient::ApiError => e
+        if e.status == 404
+          $stderr.puts "Error: @#{handle} not found on InventList."
+        else
+          $stderr.puts "Error: #{e.message}"
+        end
+      end
+
       desc "add HANDLE", "Add a teammate to a synced vault via key slot"
       method_option :vault, type: :string, aliases: "-v"
+      method_option :scope, type: :array, desc: "Groups or keys to share (omit for full access)"
+      # Grant a user access to a synced vault by creating a key slot.
+      #
+      # With --scope, creates a per-member encrypted blob containing only the
+      # specified keys. Without --scope, grants full vault access.
+      # Requires the vault to be a team vault (run team init first).
       def add(handle)
         unless Config.token
-          $stderr.puts "Error: Not logged in. Run: localvault login TOKEN"
+          $stderr.puts "Error: Not logged in."
+          $stderr.puts "\n  localvault login YOUR_TOKEN\n"
+          $stderr.puts "Get your token at: https://inventlist.com/settings"
           return
         end
 
@@ -58,55 +187,99 @@ module LocalVault
 
         handle = handle.delete_prefix("@")
         vault_name = options[:vault] || Config.default_vault
+        scope_list = options[:scope]
 
-        # Need master key from session
         master_key = SessionCache.get(vault_name)
         unless master_key
           $stderr.puts "Error: Vault '#{vault_name}' is not unlocked. Run: localvault show -v #{vault_name}"
           return
         end
 
-        # Fetch recipient's public key
         client = ApiClient.new(token: Config.token)
+
+        # Load existing bundle — must be a team vault (v3)
+        existing_blob = client.pull_vault(vault_name) rescue nil
+        unless existing_blob.is_a?(String) && !existing_blob.empty?
+          $stderr.puts "Error: Vault '#{vault_name}' is not a team vault. Run: localvault team init -v #{vault_name}"
+          return
+        end
+
+        data = SyncBundle.unpack(existing_blob)
+        unless data[:owner]
+          $stderr.puts "Error: Vault '#{vault_name}' is not a team vault. Run: localvault team init -v #{vault_name}"
+          return
+        end
+
+        # Only owner can add members
+        unless data[:owner] == Config.inventlist_handle
+          $stderr.puts "Error: Only the vault owner (@#{data[:owner]}) can manage team access."
+          return
+        end
+
+        key_slots = data[:key_slots].is_a?(Hash) ? data[:key_slots] : {}
+
+        # Check if member already has full access
+        if key_slots.key?(handle) && key_slots[handle].is_a?(Hash) && key_slots[handle]["scopes"].nil?
+          if scope_list
+            $stdout.puts "@#{handle} already has full vault access."
+            return
+          end
+        end
+
+        # Fetch recipient's public key
         result = client.get_public_key(handle)
         pub_key = result["public_key"]
-
         unless pub_key && !pub_key.empty?
           $stderr.puts "Error: @#{handle} has no public key published."
           return
         end
 
-        # Load existing key slots from remote
-        existing_blob = client.pull_vault(vault_name) rescue nil
-        key_slots = if existing_blob.is_a?(String) && !existing_blob.empty?
-                      data = SyncBundle.unpack(existing_blob)
-                      data[:key_slots].is_a?(Hash) ? data[:key_slots] : {}
-                    else
-                      {}
-                    end
-
-        # Create key slot for recipient
-        begin
-          enc_key = KeySlot.create(master_key, pub_key)
-        rescue ArgumentError, KeySlot::DecryptionError => e
-          $stderr.puts "Error: @#{handle}'s public key is invalid: #{e.message}"
-          return
-        end
-        key_slots[handle] = { "pub" => pub_key, "enc_key" => enc_key }
+        if scope_list
+          # Accumulate scopes if member already has some
+          existing_scopes = key_slots.dig(handle, "scopes") || []
+          merged_scopes = (existing_scopes + scope_list).uniq
+
+          # Create per-member blob with filtered secrets
+          vault = Vault.new(name: vault_name, master_key: master_key)
+          filtered = vault.filter(merged_scopes)
+
+          member_key = RbNaCl::Random.random_bytes(32)
+          encrypted_blob = Crypto.encrypt(JSON.generate(filtered), member_key)
+
+          begin
+            enc_key = KeySlot.create(member_key, pub_key)
+          rescue ArgumentError, KeySlot::DecryptionError => e
+            $stderr.puts "Error: @#{handle}'s public key is invalid: #{e.message}"
+            return
+          end
 
-        # Ensure owner slot exists too
-        owner_handle = Config.inventlist_handle
-        unless key_slots.key?(owner_handle)
-          owner_pub = Identity.public_key
-          key_slots[owner_handle] = { "pub" => owner_pub, "enc_key" => KeySlot.create(master_key, owner_pub) }
+          key_slots[handle] = {
+            "pub" => pub_key,
+            "enc_key" => enc_key,
+            "scopes" => merged_scopes,
+            "blob" => Base64.strict_encode64(encrypted_blob)
+          }
+        else
+          # Full vault access — encrypt master key directly
+          begin
+            enc_key = KeySlot.create(master_key, pub_key)
+          rescue ArgumentError, KeySlot::DecryptionError => e
+            $stderr.puts "Error: @#{handle}'s public key is invalid: #{e.message}"
+            return
+          end
+
+          key_slots[handle] = { "pub" => pub_key, "enc_key" => enc_key, "scopes" => nil, "blob" => nil }
         end
 
-        # Pack and push
         store = Store.new(vault_name)
-        blob = SyncBundle.pack(store, key_slots: key_slots)
+        blob = SyncBundle.pack_v3(store, owner: data[:owner], key_slots: key_slots)
         client.push_vault(vault_name, blob)
 
-        $stdout.puts "Added @#{handle} to vault '#{vault_name}'."
+        if scope_list
+          $stdout.puts "Added @#{handle} to vault '#{vault_name}' (scopes: #{key_slots[handle]["scopes"].join(", ")})."
+        else
+          $stdout.puts "Added @#{handle} to vault '#{vault_name}'."
+        end
       rescue ApiClient::ApiError => e
         if e.status == 404
           $stderr.puts "Error: @#{handle} not found or has no public key."
@@ -120,9 +293,22 @@ module LocalVault
       desc "remove HANDLE", "Remove a person's access to a vault"
       method_option :vault, type: :string, aliases: "-v"
       method_option :rotate, type: :boolean, default: false, desc: "Re-encrypt vault with new master key (full revocation)"
+      method_option :scope, type: :array, desc: "Remove specific scopes only (keeps other scopes)"
+      # Remove a user's access to a vault.
+      #
+      # Removes the user's key slot and pushes the updated bundle. With +--rotate+,
+      # re-encrypts the vault with a new master key and recreates all remaining
+      # key slots for full cryptographic revocation. Falls back to revoking a
+      # direct share if no key slots exist.
       def remove(handle)
         unless Config.token
-          $stderr.puts "Error: Not connected. Run: localvault connect --token TOKEN --handle HANDLE"
+          $stderr.puts "Error: Not logged in."
+          $stderr.puts
+          $stderr.puts "  localvault login YOUR_TOKEN"
+          $stderr.puts
+          $stderr.puts "Get your token at: https://inventlist.com/settings"
+          $stderr.puts "New to InventList? Sign up free at https://inventlist.com"
+          $stderr.puts "Docs: https://inventlist.com/sites/localvault/series/localvault"
           return
         end
 
@@ -131,9 +317,20 @@ module LocalVault
         client = ApiClient.new(token: Config.token)
 
         # Try sync-based key slot removal first
-        key_slots = load_key_slots(client, vault_name)
-        if key_slots && !key_slots.empty?
-          remove_key_slot(handle, vault_name, key_slots, client, rotate: options[:rotate])
+        team_data = load_team_data(client, vault_name)
+        if team_data && team_data[:key_slots] && !team_data[:key_slots].empty?
+          # Must be a v3 team vault with owner
+          unless team_data[:owner]
+            $stderr.puts "Error: Vault '#{vault_name}' is not a team vault. Run: localvault team init -v #{vault_name}"
+            return
+          end
+          unless team_data[:owner] == Config.inventlist_handle
+            $stderr.puts "Error: Only the vault owner (@#{team_data[:owner]}) can manage team access."
+            return
+          end
+          remove_key_slot(handle, vault_name, team_data[:key_slots], client,
+                          rotate: options[:rotate], remove_scopes: options[:scope],
+                          owner: team_data[:owner])
           return
         end
 
@@ -154,25 +351,154 @@ module LocalVault
         $stderr.puts "Error: #{e.message}"
       end
 
+      desc "rotate", "Re-encrypt a team vault with a new master key (no member changes)"
+      method_option :vault, type: :string, aliases: "-v"
+      # Re-key a team vault without adding or removing members.
+      #
+      # Prompts for a new passphrase, re-encrypts all secrets, and rebuilds
+      # all key slots. Useful for periodic key rotation.
+      def rotate
+        unless Config.token
+          $stderr.puts "Error: Not logged in."
+          return
+        end
+
+        vault_name = options[:vault] || Config.default_vault
+        client = ApiClient.new(token: Config.token)
+
+        team_data = load_team_data(client, vault_name)
+        unless team_data && team_data[:key_slots] && !team_data[:key_slots].empty?
+          $stderr.puts "Error: Vault '#{vault_name}' has no team access. Nothing to rotate."
+          return
+        end
+
+        unless team_data[:owner]
+          $stderr.puts "Error: Vault '#{vault_name}' is not a team vault. Run: localvault team init -v #{vault_name}"
+          return
+        end
+
+        unless team_data[:owner] == Config.inventlist_handle
+          $stderr.puts "Error: Only the vault owner (@#{team_data[:owner]}) can rotate keys."
+          return
+        end
+
+        key_slots = team_data[:key_slots]
+        vault_owner = team_data[:owner]
+
+        master_key = SessionCache.get(vault_name)
+        unless master_key
+          $stderr.puts "Error: Vault '#{vault_name}' is not unlocked."
+          return
+        end
+
+        passphrase = prompt_passphrase("New passphrase for vault '#{vault_name}': ")
+        if passphrase.nil? || passphrase.empty?
+          $stderr.puts "Error: Passphrase cannot be empty."
+          return
+        end
+
+        vault = Vault.new(name: vault_name, master_key: master_key)
+        secrets = vault.all
+        store = Store.new(vault_name)
+
+        new_salt = Crypto.generate_salt
+        new_master_key = Crypto.derive_master_key(passphrase, new_salt)
+
+        store.write_encrypted(Crypto.encrypt(JSON.generate(secrets), new_master_key))
+        store.create_meta!(salt: new_salt)
+
+        new_slots = {}
+        key_slots.each do |h, slot|
+          next unless slot.is_a?(Hash) && slot["pub"].is_a?(String)
+          if slot["scopes"].is_a?(Array)
+            filtered = vault.filter(slot["scopes"])
+            member_key = RbNaCl::Random.random_bytes(32)
+            encrypted_blob = Crypto.encrypt(JSON.generate(filtered), member_key)
+            new_slots[h] = { "pub" => slot["pub"], "enc_key" => KeySlot.create(member_key, slot["pub"]), "scopes" => slot["scopes"], "blob" => Base64.strict_encode64(encrypted_blob) }
+          else
+            new_slots[h] = { "pub" => slot["pub"], "enc_key" => KeySlot.create(new_master_key, slot["pub"]), "scopes" => nil, "blob" => nil }
+          end
+        end
+
+        blob = SyncBundle.pack_v3(store, owner: vault_owner, key_slots: new_slots)
+        client.push_vault(vault_name, blob)
+        SessionCache.set(vault_name, new_master_key)
+
+        $stdout.puts "Vault '#{vault_name}' re-encrypted with new master key."
+        $stdout.puts "#{new_slots.size} member(s) updated."
+      rescue ApiClient::ApiError => e
+        $stderr.puts "Error: #{e.message}"
+      end
+
       private
 
+      def prompt_passphrase(msg = "Passphrase: ")
+        IO.console&.getpass(msg) || $stdin.gets&.chomp || ""
+      rescue Interrupt
+        $stderr.puts
+        ""
+      end
+
       def load_key_slots(client, vault_name)
+        data = load_team_data(client, vault_name)
+        data ? data[:key_slots] : nil
+      end
+
+      # Load full bundle data including owner. Returns nil if no remote or not a team vault.
+      def load_team_data(client, vault_name)
         return nil unless client.respond_to?(:pull_vault)
         blob = client.pull_vault(vault_name)
         return nil unless blob.is_a?(String) && !blob.empty?
         data = SyncBundle.unpack(blob)
-        slots = data[:key_slots]
-        slots.is_a?(Hash) ? slots : nil
+        return nil unless data[:key_slots].is_a?(Hash)
+        data
       rescue ApiClient::ApiError, SyncBundle::UnpackError, NoMethodError
         nil
       end
 
-      def remove_key_slot(handle, vault_name, key_slots, client, rotate: false)
+      # Remove a member's key slot, optionally rotating the vault master key.
+      # Supports partial scope removal via remove_scopes.
+      def remove_key_slot(handle, vault_name, key_slots, client, rotate: false, remove_scopes: nil, owner: nil)
+        owner ||= Config.inventlist_handle
         unless key_slots.key?(handle)
           $stderr.puts "Error: @#{handle} has no slot in vault '#{vault_name}'."
           return
         end
 
+        store = Store.new(vault_name)
+
+        # Partial scope removal
+        if remove_scopes && key_slots[handle].is_a?(Hash) && key_slots[handle]["scopes"].is_a?(Array)
+          remaining = key_slots[handle]["scopes"] - remove_scopes
+          if remaining.empty?
+            # Last scope removed — remove member entirely
+            key_slots.delete(handle)
+            $stdout.puts "Removed @#{handle} from vault '#{vault_name}' (last scope removed)."
+          else
+            # Rebuild blob with remaining scopes
+            master_key = SessionCache.get(vault_name)
+            if master_key
+              vault = Vault.new(name: vault_name, master_key: master_key)
+              filtered = vault.filter(remaining)
+              member_key = RbNaCl::Random.random_bytes(32)
+              encrypted_blob = Crypto.encrypt(JSON.generate(filtered), member_key)
+              enc_key = KeySlot.create(member_key, key_slots[handle]["pub"])
+              key_slots[handle] = {
+                "pub" => key_slots[handle]["pub"],
+                "enc_key" => enc_key,
+                "scopes" => remaining,
+                "blob" => Base64.strict_encode64(encrypted_blob)
+              }
+            end
+            $stdout.puts "Removed scope(s) #{remove_scopes.join(", ")} from @#{handle}. Remaining: #{remaining.join(", ")}"
+          end
+
+          blob = SyncBundle.pack_v3(store, owner: owner, key_slots: key_slots)
+          client.push_vault(vault_name, blob)
+          return
+        end
+
+        # Full member removal
         valid_slots = key_slots.select { |_, v| v.is_a?(Hash) && v["pub"].is_a?(String) }
         if handle == Config.inventlist_handle && valid_slots.size <= 1
           $stderr.puts "Error: Cannot remove yourself — you are the only member."
@@ -180,7 +506,6 @@ module LocalVault
         end
 
         key_slots.delete(handle)
-        store = Store.new(vault_name)
 
         if rotate
           master_key = SessionCache.get(vault_name)
@@ -189,30 +514,47 @@ module LocalVault
             return
           end
 
-          # Decrypt current secrets, generate new master key, re-encrypt
+          # Prompt for new passphrase
+          passphrase = prompt_passphrase("New passphrase for vault '#{vault_name}': ")
+          if passphrase.nil? || passphrase.empty?
+            $stderr.puts "Error: Passphrase cannot be empty."
+            return
+          end
+
           vault = Vault.new(name: vault_name, master_key: master_key)
           secrets = vault.all
 
           new_salt = Crypto.generate_salt
-          new_master_key = Crypto.derive_master_key(SecureRandom.hex(32), new_salt)
+          new_master_key = Crypto.derive_master_key(passphrase, new_salt)
 
-          # Re-encrypt secrets with new master key
           new_json = JSON.generate(secrets)
           new_encrypted = Crypto.encrypt(new_json, new_master_key)
           store.write_encrypted(new_encrypted)
           store.create_meta!(salt: new_salt)
 
-          # Re-create key slots for remaining members with new master key
           new_slots = {}
           key_slots.each do |h, slot|
             next unless slot.is_a?(Hash) && slot["pub"].is_a?(String)
-            new_slots[h] = { "pub" => slot["pub"], "enc_key" => KeySlot.create(new_master_key, slot["pub"]) }
+            if slot["scopes"].is_a?(Array)
+              # Scoped member — rebuild per-member blob
+              filtered = vault.filter(slot["scopes"])
+              member_key = RbNaCl::Random.random_bytes(32)
+              encrypted_blob = Crypto.encrypt(JSON.generate(filtered), member_key)
+              new_slots[h] = {
+                "pub" => slot["pub"],
+                "enc_key" => KeySlot.create(member_key, slot["pub"]),
+                "scopes" => slot["scopes"],
+                "blob" => Base64.strict_encode64(encrypted_blob)
+              }
+            else
+              # Full-access member
+              new_slots[h] = { "pub" => slot["pub"], "enc_key" => KeySlot.create(new_master_key, slot["pub"]), "scopes" => nil, "blob" => nil }
+            end
           end
 
-          blob = SyncBundle.pack(store, key_slots: new_slots)
+          blob = SyncBundle.pack_v3(store, owner: owner, key_slots: new_slots)
           client.push_vault(vault_name, blob)
 
-          # Only cache new master key if the caller is still a member
           if new_slots.key?(Config.inventlist_handle)
             SessionCache.set(vault_name, new_master_key)
           else
@@ -222,7 +564,7 @@ module LocalVault
           $stdout.puts "Removed @#{handle} from vault '#{vault_name}'."
           $stdout.puts "Vault re-encrypted with new master key (rotated)."
         else
-          blob = SyncBundle.pack(store, key_slots: key_slots)
+          blob = SyncBundle.pack_v3(store, owner: owner, key_slots: key_slots)
           client.push_vault(vault_name, blob)
           $stdout.puts "Removed @#{handle} from vault '#{vault_name}'."
         end

data/lib/localvault/cli.rb

@@ -8,6 +8,61 @@ module LocalVault
   class CLI < Thor
     class_option :vault, aliases: "-v", type: :string, desc: "Vault name"
 
+    def self.help(shell, subcommand = false)
+      shell.say ""
+      shell.say "LocalVault — encrypted local secrets vault with MCP support for AI agents"
+      shell.say "  https://inventlist.com/tools/localvault"
+      shell.say ""
+      shell.say "GETTING STARTED"
+      shell.say "  localvault login [TOKEN]      Log in to InventList (enables sync + team features)"
+      shell.say "  localvault init [NAME]        Create a new encrypted vault"
+      shell.say "  localvault demo               Create a demo vault to explore commands"
+      shell.say ""
+      shell.say "SECRETS"
+      shell.say "  localvault set KEY VALUE      Store a secret"
+      shell.say "  localvault get KEY            Retrieve a secret"
+      shell.say "  localvault show               Display all secrets (masked by default)"
+      shell.say "  localvault list               List secret key names"
+      shell.say "  localvault delete KEY         Remove a secret"
+      shell.say "  localvault import FILE        Bulk-import from .env / .json / .yml"
+      shell.say "  localvault env                Export as shell variable assignments"
+      shell.say "  localvault exec -- CMD        Run a command with secrets injected"
+      shell.say ""
+      shell.say "VAULT MANAGEMENT"
+      shell.say "  localvault vaults             List all vaults"
+      shell.say "  localvault switch [VAULT]     Switch default vault"
+      shell.say "  localvault rekey [NAME]       Change vault passphrase"
+      shell.say "  localvault unlock             Cache passphrase for session"
+      shell.say "  localvault lock [NAME]        Clear cached passphrase"
+      shell.say "  localvault reset [NAME]       Destroy and reinitialize a vault"
+      shell.say "  localvault rename OLD NEW     Rename a secret key"
+      shell.say "  localvault copy KEY --to V    Copy a secret to another vault"
+      shell.say ""
+      shell.say "TEAM & SYNC  (requires localvault login)"
+      shell.say "  localvault sync push [NAME]   Push vault to cloud"
+      shell.say "  localvault sync pull [NAME]   Pull vault from cloud"
+      shell.say "  localvault sync status        Show sync status"
+      shell.say "  localvault team init          Convert vault to team vault (required before team add)"
+      shell.say "  localvault team add HANDLE    Add teammate (use --scope KEY... for partial access)"
+      shell.say "  localvault team remove HANDLE Remove teammate  (--scope KEY to strip one key, --rotate to re-key)"
+      shell.say "  localvault team list          List vault members and their access"
+      shell.say "  localvault team rotate        Re-key vault, keep all members"
+      shell.say "  localvault keys generate      Generate X25519 identity keypair"
+      shell.say "  localvault keys publish       Publish public key so others can share vaults with you"
+      shell.say "  localvault keys show          Display your current public key"
+      shell.say ""
+      shell.say "AI / MCP"
+      shell.say "  localvault install-mcp        Configure MCP server in your AI tool"
+      shell.say "  localvault mcp                Start MCP server (stdio)"
+      shell.say ""
+      shell.say "OTHER"
+      shell.say "  localvault login --status     Show current login status"
+      shell.say "  localvault logout             Log out"
+      shell.say "  localvault version            Print version"
+      shell.say "  localvault help [COMMAND]     Full help for any command"
+      shell.say ""
+    end
+
     desc "init [NAME]", "Create a new vault"
     def init(name = nil)
       vault_name = name || Config.default_vault
@@ -487,8 +542,15 @@ module LocalVault
       end
 
       unless token
-        $stdout.puts "Usage: localvault login TOKEN"
+        $stdout.puts "Usage: localvault login YOUR_TOKEN"
+        $stdout.puts
         $stdout.puts "Get your token at: https://inventlist.com/settings"
+        $stdout.puts "New to InventList? Sign up free at https://inventlist.com"
+        $stdout.puts
+        $stdout.puts "LocalVault sync and team features require a free InventList account."
+        $stdout.puts "Local vault encryption works without an account."
+        $stdout.puts
+        $stdout.puts "Docs: https://inventlist.com/sites/localvault/series/localvault"
         return
       end
 
@@ -547,7 +609,7 @@ module LocalVault
       desc: "Recipient: @handle, team:HANDLE, or crew:SLUG"
     def share(vault_name = nil)
       unless Config.token
-        abort_with "Not connected. Run: localvault connect --token TOKEN --handle HANDLE"
+        abort_with "Not logged in. Run: localvault login YOUR_TOKEN\n  Get your token at: https://inventlist.com/settings"
         return
       end
 
@@ -590,7 +652,7 @@ module LocalVault
     desc "receive", "Fetch and import vaults shared with you"
     def receive
       unless Config.token
-        abort_with "Not connected. Run: localvault connect --token TOKEN --handle HANDLE"
+        abort_with "Not logged in. Run: localvault login YOUR_TOKEN\n  Get your token at: https://inventlist.com/settings"
         return
       end
 
@@ -658,7 +720,7 @@ module LocalVault
     desc "revoke SHARE_ID", "Revoke a vault share (stops future access)"
     def revoke(share_id)
       unless Config.token
-        abort_with "Not connected. Run: localvault connect --token TOKEN --handle HANDLE"
+        abort_with "Not logged in. Run: localvault login YOUR_TOKEN\n  Get your token at: https://inventlist.com/settings"
         return
       end