Improve onboarding experience for new users

- Auto-redirect `keep` (no args) to `init` when uninitialized
- Add isAvailable() checks on vault drivers for missing AWS SDK
- Show actionable KeepException when no vaults configured
- Pre-check AWS credentials via STS before running permission matrix

Author: jszobody

src/Commands/Concerns/ConfiguresVaults.php

@@ -18,18 +18,27 @@ trait ConfiguresVaults
 {
     protected function configureNewVault(): ?array
     {
-        // Get available vault classes and build options
         $availableVaults = Keep::getAvailableVaults();
         $driverOptions = [];
         $vaultClassMap = [];
 
         foreach ($availableVaults as $vaultClass) {
+            if (!$vaultClass::isAvailable()) {
+                continue;
+            }
             $driver = $vaultClass::DRIVER;
             $name = $vaultClass::NAME;
             $driverOptions[$driver] = $name;
             $vaultClassMap[$driver] = $vaultClass;
         }
 
+        if (empty($driverOptions)) {
+            error('No vault drivers are available. The AWS SDK is required.');
+            info('Install it with: composer require aws/aws-sdk-php');
+
+            return null;
+        }
+
         $selectedDriver = select(
             label: 'Which vault driver would you like to use?',
             options: $driverOptions
@@ -79,7 +88,6 @@ protected function configureNewVault(): ?array
         info("✅ {$friendlyName} vault '{$slug}' configured successfully");
 
         // Reload vault configurations to include the newly saved vault
-        // This ensures the permission tester can find and update the vault
         $container = \STS\Keep\KeepContainer::getInstance();
         $container->instance(
             \STS\Keep\KeepManager::class,
@@ -88,12 +96,24 @@ protected function configureNewVault(): ?array
                 \STS\Keep\Data\Collections\VaultConfigCollection::load()
             )
         );
-        
-        // Run verify to check and cache permissions for all environments
+
+        $region = $vaultConfig['region'] ?? 'us-east-1';
+        if (!$this->checkAwsCredentials($region)) {
+            info('');
+            error('AWS credentials not found or invalid.');
+            info('Configure credentials via:');
+            info('  - AWS CLI: aws configure');
+            info('  - Environment variables: AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY');
+            info('  - Instance profile (on EC2/ECS/Lambda)');
+            info('');
+            info('Skipping permission verification. Run "keep verify" once credentials are configured.');
+
+            return ['slug' => $slug, 'config' => $vaultConfig];
+        }
+
         info("\nVerifying vault permissions...");
         $collection = $this->testVaultAcrossEnvs($slug);
-        
-        // Display summary of permissions
+
         foreach ($collection->groupByEnv() as $env => $permissions) {
             $permission = $permissions->first();
             $permString = empty($permission->permissions()) ? 'no permissions' : implode(', ', $permission->permissions());
@@ -129,6 +149,26 @@ protected function testVaultAcrossEnvs(string $vaultName): PermissionsCollection
         return $collection;
     }
 
+    protected function checkAwsCredentials(string $region): bool
+    {
+        if (!class_exists(\Aws\Sts\StsClient::class)) {
+            return false;
+        }
+
+        try {
+            $sts = new \Aws\Sts\StsClient([
+                'version' => 'latest',
+                'region' => $region,
+                'use_aws_shared_config_files' => true,
+            ]);
+            $sts->getCallerIdentity();
+
+            return true;
+        } catch (\Exception) {
+            return false;
+        }
+    }
+
     private function generateUniqueSlug(string $driver): string
     {
         $existingVaults = Keep::getConfiguredVaults();

src/Commands/Concerns/GathersInput.php

@@ -66,7 +66,7 @@ protected function vaultName($prompt = 'Vault', $cacheName = 'vaultName'): strin
     {
         return $this->{$cacheName} ??= match (true) {
             $this->hasOption('vault') && (bool) $this->option('vault') => $this->option('vault'),
-            Keep::getConfiguredVaults()->count() === 0 => throw new \RuntimeException('No vaults are configured. Please add a vault first with: keep vault:add.'),
+            Keep::getConfiguredVaults()->count() === 0 => throw (new KeepException('No vaults are configured.'))->withContext(['suggestion' => 'Add your first vault with: keep vault:add']),
             Keep::getConfiguredVaults()->count() === 1 => Keep::getConfiguredVaults()->first()->slug(),
             default => select($prompt, Keep::getConfiguredVaults()->keys()->toArray(), Keep::getDefaultVault()),
         };

src/Commands/ShellCommand.php

@@ -2,20 +2,39 @@
 
 namespace STS\Keep\Commands;
 
+use STS\Keep\Facades\Keep;
 use STS\Keep\Shell\SimpleShell;
 use STS\Keep\Shell\ShellContext;
 
 class ShellCommand extends BaseCommand
 {
-    protected $signature = 'shell 
+    protected $signature = 'shell
         {--env= : Initial environment to use}
         {--vault= : Initial vault to use}';
-    
+
     protected $description = 'Start an interactive shell for Keep commands';
-    
+
+    protected function requiresInitialization(): bool
+    {
+        return false;
+    }
+
     public function process()
     {
-        // Check if readline is available
+        if (!Keep::isInitialized()) {
+            $this->line('');
+            $this->line('<info>Welcome to Keep!</info> Secret management for your team.');
+            $this->line('');
+
+            $this->call('init');
+
+            if (!Keep::isInitialized()) {
+                return self::SUCCESS;
+            }
+
+            $this->line('');
+        }
+
         if (!function_exists('readline')) {
             $this->error('The readline extension is required to run the Keep shell.');
             $this->line('Please install the readline PHP extension.');

src/KeepManager.php

@@ -110,6 +110,12 @@ public function vault(string $name, string $env): AbstractVault
             throw new \InvalidArgumentException("Vault driver '{$driver}' for '{$name}' is not available.");
         }
 
+        if (!$driverClass::isAvailable()) {
+            throw new \RuntimeException(
+                "Vault driver '{$driver}' requires the AWS SDK. Install it with: composer require aws/aws-sdk-php"
+            );
+        }
+
         $vault = new $driverClass($name, $config->toArray(), $env);
         $this->loadedVaults[$cacheKey] = $vault;
 

src/Vaults/AbstractVault.php

@@ -16,6 +16,11 @@ abstract class AbstractVault
 
     public const string NAME = '';
 
+    public static function isAvailable(): bool
+    {
+        return true;
+    }
+
     public function __construct(protected string $name, protected array $config, protected string $env) {}
 
     public function name(): string

src/Vaults/AwsSecretsManagerVault.php

@@ -26,6 +26,11 @@ class AwsSecretsManagerVault extends AbstractVault
 
     protected SecretsManagerClient $client;
 
+    public static function isAvailable(): bool
+    {
+        return class_exists(SecretsManagerClient::class);
+    }
+
     public static function configure(array $existingSettings = []): array
     {
         return [

src/Vaults/AwsSsmVault.php

@@ -28,6 +28,11 @@ class AwsSsmVault extends AbstractVault
 
     protected SsmClient $client;
 
+    public static function isAvailable(): bool
+    {
+        return class_exists(SsmClient::class);
+    }
+
     public static function configure(array $existingSettings = []): array
     {
         return [