axvault 1.6.0 → 1.7.0

package/README.md

@@ -2,6 +2,57 @@
 
 Remote credential storage server for a╳kit.
 
+## Quick start
+
+```bash
+export AXVAULT_ENCRYPTION_KEY="your-secret-key-minimum-32-chars!"
+axvault init
+axvault serve
+```
+
+In another shell, create an API key:
+
+```bash
+axvault key create --name "Admin" --read "*" --write "*" --grant "*"
+```
+
+Add `--verbose` to commands like `init`, `serve`, `key revoke`, `key update`, and
+`credential delete` to see status output.
+
+## Pipeline examples
+
+### Extract key IDs
+
+```bash
+axvault key list | tail -n +2 | cut -f1
+```
+
+### Count credentials by type
+
+```bash
+axvault credential list | tail -n +2 | cut -f3 | sort | uniq -c | sort -rn
+```
+
+### List credential paths for a single agent
+
+```bash
+axvault credential list | tail -n +2 | awk -F'\t' '$1 == "claude" {print $1 "/" $2}'
+```
+
+## Agent Rule
+
+Add to your `CLAUDE.md` or `AGENTS.md`:
+
+```markdown
+# Rule: `axvault` Usage
+
+Run `npx -y axvault --help` to learn available options.
+
+Use `axvault` when you need to initialize the vault database, manage API keys,
+or list/delete stored credentials. It outputs TSV tables for list commands, so
+you can pipe them into standard Unix tools.
+```
+
 ## Configuration
 
 ### Environment Variables
@@ -100,9 +151,11 @@ axvault key update k_a1b2c3d4e5f6 --add-read "codex/ci" --remove-write "claude/d
 ### Revoke a Key
 
 ```bash
-axvault key revoke k_a1b2c3d4e5f6
+axvault key revoke k_a1b2c3d4e5f6 --force
 ```
 
+This command requires `--force` or `--yes` to confirm.
+
 ### Container Deployments
 
 #### Running the Container

package/dist/cli.js

@@ -40,21 +40,25 @@ Examples:
   # List all API keys
   axvault key list
 
+  # Extract key IDs for scripting (pipeline example)
+  axvault key list | tail -n +2 | cut -f1
+
   # Update an API key's permissions
   axvault key update k_abc123def456 --add-read "claude/new"
 
   # Revoke an API key
-  axvault key revoke k_abc123def456
+  axvault key revoke k_abc123def456 --force
 
   # List all stored credentials
   axvault credential list
 
   # Delete a credential
-  axvault credential delete claude/work`);
+  axvault credential delete claude/work --force`);
 program
     .command("init")
     .description("Initialize database and configuration")
     .option("--db-path <path>", "Database file path")
+    .option("-v, --verbose", "Enable verbose output")
     .action(handleInit);
 program
     .command("serve")
@@ -64,6 +68,7 @@ program
     .option("--db-path <path>", "Database file path")
     .option("--refresh-threshold <seconds>", "Refresh credentials expiring within this many seconds (0 to disable)")
     .option("--refresh-timeout <ms>", "Timeout for refresh operations in milliseconds")
+    .option("-v, --verbose", "Enable verbose output")
     .action(handleServe);
 // API key management commands
 const keyCommand = program
@@ -90,6 +95,9 @@ keyCommand
     .command("revoke")
     .description("Revoke an API key")
     .argument("<id>", "API key ID (e.g., k_abc123def456)")
+    .option("-f, --force", "Confirm destructive action")
+    .option("-y, --yes", "Alias for --force")
+    .option("-v, --verbose", "Enable verbose output")
     .option("--db-path <path>", "Database file path")
     .action(handleKeyRevoke);
 keyCommand
@@ -103,6 +111,7 @@ keyCommand
     .option("--remove-write <access>", "Remove write access entries")
     .option("--remove-grant <access>", "Remove grant access entries")
     .option("--json", "Output as JSON")
+    .option("-v, --verbose", "Enable verbose output")
     .option("--db-path <path>", "Database file path")
     .action(handleKeyUpdate);
 // Credential management commands
@@ -120,6 +129,9 @@ credentialCommand
     .command("delete")
     .description("Delete a credential")
     .argument("<path>", "Credential path (agent/name, e.g., claude/work)")
+    .option("-f, --force", "Confirm destructive action")
+    .option("-y, --yes", "Alias for --force")
+    .option("-v, --verbose", "Enable verbose output")
     .option("--db-path <path>", "Database file path")
     .action(handleCredentialDelete);
 await program.parseAsync(process.argv);

package/dist/commands/credential.d.ts

@@ -7,6 +7,9 @@ interface CredentialListOptions {
 }
 interface CredentialDeleteOptions {
     dbPath?: string;
+    force?: boolean;
+    yes?: boolean;
+    verbose?: boolean;
 }
 export declare function handleCredentialList(options: CredentialListOptions): void;
 export declare function handleCredentialDelete(path: string, options: CredentialDeleteOptions): void;

package/dist/commands/credential.js

@@ -91,6 +91,12 @@ export function handleCredentialDelete(path, options) {
         process.exitCode = 2;
         return;
     }
+    if (!options.force && !options.yes) {
+        console.error("Error: Deleting a credential is destructive. Re-run with --force or --yes to confirm.");
+        console.error("Try 'axvault credential delete --help' for more information.");
+        process.exitCode = 2;
+        return;
+    }
     const { agent, name } = parsed;
     try {
         const config = getServerConfig(options);
@@ -98,7 +104,9 @@ export function handleCredentialDelete(path, options) {
         runMigrations(database);
         const deleted = deleteCredential(database, agent, name);
         if (deleted) {
-            console.error(`Deleted credential: ${sanitizeForTsv(agent)}/${sanitizeForTsv(name)}`);
+            if (options.verbose) {
+                console.error(`Deleted credential: ${sanitizeForTsv(agent)}/${sanitizeForTsv(name)}`);
+            }
         }
         else {
             console.error(`Error: Credential not found: ${sanitizeForTsv(agent)}/${sanitizeForTsv(name)}`);

package/dist/commands/init.d.ts

@@ -3,6 +3,7 @@
  */
 interface InitOptions {
     dbPath?: string;
+    verbose?: boolean;
 }
 export declare function handleInit(options: InitOptions): void;
 export {};

package/dist/commands/init.js

@@ -7,13 +7,15 @@ import { getServerConfig } from "../config.js";
 import { closeDatabase, getDatabase } from "../db/client.js";
 import { CURRENT_VERSION, getSchemaVersion, runMigrations, } from "../db/migrations.js";
 export function handleInit(options) {
-    const config = getServerConfig(options);
+    const config = getServerConfig({ dbPath: options.dbPath });
+    const verbose = options.verbose === true;
     // Ensure data directory exists
     const dataDirectory = path.dirname(config.databasePath);
     if (!existsSync(dataDirectory)) {
         try {
             mkdirSync(dataDirectory, { recursive: true });
-            console.error(`Created data directory: ${dataDirectory}`);
+            if (verbose)
+                console.error(`Created data directory: ${dataDirectory}`);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -28,15 +30,17 @@ export function handleInit(options) {
         const versionBefore = getSchemaVersion(database);
         runMigrations(database);
         const versionAfter = getSchemaVersion(database);
-        if (versionBefore === 0) {
-            console.error(`Database initialized at: ${config.databasePath}`);
-            console.error(`Schema version: ${versionAfter}`);
-        }
-        else if (versionBefore < versionAfter) {
-            console.error(`Database migrated from v${versionBefore} to v${versionAfter}`);
-        }
-        else {
-            console.error(`Database already at version ${versionAfter} (current: ${CURRENT_VERSION})`);
+        if (verbose) {
+            if (versionBefore === 0) {
+                console.error(`Database initialized at: ${config.databasePath}`);
+                console.error(`Schema version: ${versionAfter}`);
+            }
+            else if (versionBefore < versionAfter) {
+                console.error(`Database migrated from v${versionBefore} to v${versionAfter}`);
+            }
+            else {
+                console.error(`Database already at version ${versionAfter} (current: ${CURRENT_VERSION})`);
+            }
         }
     }
     catch (error) {

package/dist/commands/key-revoke.d.ts

@@ -3,6 +3,9 @@
  */
 interface KeyRevokeOptions {
     dbPath?: string;
+    force?: boolean;
+    yes?: boolean;
+    verbose?: boolean;
 }
 export declare function handleKeyRevoke(id: string, options: KeyRevokeOptions): void;
 export {};

package/dist/commands/key-revoke.js

@@ -24,13 +24,21 @@ export function handleKeyRevoke(id, options) {
         process.exitCode = 2;
         return;
     }
+    if (!options.force && !options.yes) {
+        console.error("Error: Revoking an API key is destructive. Re-run with --force or --yes to confirm.");
+        console.error("Try 'axvault key revoke --help' for more information.");
+        process.exitCode = 2;
+        return;
+    }
     try {
         const config = getServerConfig(options);
         const database = getDatabase(config.databasePath);
         runMigrations(database);
         const deleted = deleteApiKey(database, trimmedId);
         if (deleted) {
-            console.error(`Revoked API key: ${sanitizeForTsv(trimmedId)}`);
+            if (options.verbose) {
+                console.error(`Revoked API key: ${sanitizeForTsv(trimmedId)}`);
+            }
         }
         else {
             console.error(`Error: API key not found: ${sanitizeForTsv(trimmedId)}`);

package/dist/commands/key-update.d.ts

@@ -10,6 +10,7 @@ interface KeyUpdateOptions {
     removeWrite?: string;
     removeGrant?: string;
     json?: boolean;
+    verbose?: boolean;
 }
 export declare function handleKeyUpdate(id: string, options: KeyUpdateOptions): void;
 export {};

package/dist/commands/key-update.js

@@ -76,7 +76,7 @@ export function handleKeyUpdate(id, options) {
             process.exitCode = 1;
             return;
         }
-        outputKeyDetails(updatedKey, options.json ?? false);
+        outputKeyDetails(updatedKey, options.json ?? false, options.verbose ?? false);
     }
     catch (error) {
         console.error(`Error: Failed to update API key: ${getErrorMessage(error)}`);
@@ -87,7 +87,7 @@ export function handleKeyUpdate(id, options) {
     }
 }
 /** Output key details in JSON or human-readable format */
-function outputKeyDetails(key, json) {
+function outputKeyDetails(key, json, verbose) {
     if (json) {
         console.log(JSON.stringify({
             id: key.id,
@@ -99,7 +99,7 @@ function outputKeyDetails(key, json) {
             lastUsedAt: formatDateForJson(key.lastUsedAt),
         }, undefined, 2));
     }
-    else {
+    else if (verbose) {
         console.error(`Updated API key: ${sanitizeForTsv(key.name)}`);
         console.error(`ID: ${sanitizeForTsv(key.id)}`);
         console.error(`Read access: ${sanitizeForTsv(formatAccessList(key.readAccess))}`);

package/dist/commands/serve.d.ts

@@ -7,6 +7,7 @@ interface ServeOptions {
     dbPath?: string;
     refreshThreshold?: string;
     refreshTimeout?: string;
+    verbose?: boolean;
 }
 export declare function handleServe(options: ServeOptions): Promise<void>;
 export {};

package/dist/commands/serve.js

@@ -10,9 +10,12 @@ import { createHealthRouter, createCredentialRouter, } from "../server/routes.js
 import { createServer } from "../server/server.js";
 export async function handleServe(options) {
     let config;
+    const verbose = options.verbose === true;
     try {
         config = getServerConfig({
-            ...options,
+            port: options.port,
+            host: options.host,
+            dbPath: options.dbPath,
             refreshThresholdSeconds: options.refreshThreshold,
             refreshTimeoutMs: options.refreshTimeout,
         });
@@ -35,7 +38,8 @@ export async function handleServe(options) {
     if (!existsSync(dataDirectory)) {
         try {
             mkdirSync(dataDirectory, { recursive: true });
-            console.error(`Created data directory: ${dataDirectory}`);
+            if (verbose)
+                console.error(`Created data directory: ${dataDirectory}`);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -66,7 +70,8 @@ export async function handleServe(options) {
     ]);
     // Graceful shutdown handler
     const shutdown = () => {
-        console.error("Shutting down...");
+        if (verbose)
+            console.error("Shutting down...");
         server.stop().then(() => {
             closeDatabase();
             // eslint-disable-next-line unicorn/no-process-exit -- CLI graceful shutdown

package/package.json

@@ -2,7 +2,7 @@
   "name": "axvault",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Remote credential storage server for axkit",
   "repository": {
     "type": "git",