axauth 3.1.6 → 3.3.0

package/dist/auth/adapter.d.ts

@@ -241,6 +241,22 @@ interface AuthAdapter {
      * to specify which provider's token to extract.
      */
     getAccessToken(creds: Credentials, options?: TokenOptions): string | undefined;
+    /**
+     * Check whether credentials are expired.
+     *
+     * Returns:
+     * - `true` when credentials are expired (or inside refresh buffer)
+     * - `false` when credentials are valid
+     * - `undefined` when expiry cannot be determined
+     */
+    isExpired(creds: Credentials, bufferSeconds?: number): boolean | undefined;
+    /**
+     * Check whether credentials can be refreshed.
+     *
+     * Returns true when credentials contain a refresh token compatible with
+     * the adapter's underlying auth format.
+     */
+    isRefreshable(creds: Credentials): boolean;
     /**
      * Convert credentials to environment variables.
      *

package/dist/auth/agents/claude.js

@@ -5,6 +5,7 @@
  */
 import path from "node:path";
 import { extractCredsFromDirectory } from "../extract-creds-from-directory.js";
+import { isCredentialExpired, isTokenExpired } from "../is-token-expired.js";
 import { CREDS_FILE_NAME, installCredentials, removeCredentials, } from "./claude-install.js";
 import { AGENT_ID, checkAuth, findStoredCredentials as findStoredCredentialsInternal, getEnvironmentCredentials as getEnvironmentCredentialsInternal, } from "./claude-storage.js";
 /** Claude Code authentication adapter */
@@ -61,6 +62,23 @@ const claudeCodeAdapter = {
         }
         return undefined;
     },
+    isExpired(creds, bufferSeconds = 60) {
+        const data = creds.data;
+        const token = (creds.type === "oauth-credentials" || creds.type === "oauth-token") &&
+            typeof data.accessToken === "string"
+            ? data.accessToken
+            : undefined;
+        if (token) {
+            const expired = isTokenExpired(token, bufferSeconds);
+            if (expired !== undefined)
+                return expired;
+        }
+        return isCredentialExpired(data, bufferSeconds);
+    },
+    isRefreshable(creds) {
+        return (creds.type === "oauth-credentials" &&
+            typeof creds.data.refreshToken === "string");
+    },
     credentialsToEnvironment(creds) {
         const environment = {};
         const data = creds.data;

package/dist/auth/agents/codex.js

@@ -5,6 +5,7 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
+import { isCredentialExpired, isTokenExpired } from "../is-token-expired.js";
 import { checkAuth, findStoredCredentials, getEnvironmentCredentials, } from "./codex-auth-check.js";
 import { CREDS_FILE_NAME, installCodexCredentials, removeCodexCredentials, } from "./codex-install.js";
 const AGENT_ID = "codex";
@@ -61,6 +62,36 @@ const codexAdapter = {
         }
         return undefined;
     },
+    isExpired(creds, bufferSeconds = 60) {
+        const data = creds.data;
+        const token = (creds.type === "api-key" && typeof data.apiKey === "string"
+            ? data.apiKey
+            : undefined) ??
+            (creds.type === "oauth-credentials" &&
+                typeof data.access_token === "string"
+                ? data.access_token
+                : undefined) ??
+            (creds.type === "oauth-credentials" &&
+                typeof data.tokens === "object" &&
+                data.tokens !== null &&
+                typeof data.tokens.access_token === "string"
+                ? data.tokens.access_token
+                : undefined);
+        if (token) {
+            const expired = isTokenExpired(token, bufferSeconds);
+            if (expired !== undefined)
+                return expired;
+        }
+        return isCredentialExpired(data, bufferSeconds);
+    },
+    isRefreshable(creds) {
+        if (creds.type !== "oauth-credentials")
+            return false;
+        const tokens = typeof creds.data.tokens === "object" && creds.data.tokens !== null
+            ? creds.data.tokens
+            : undefined;
+        return typeof tokens?.refresh_token === "string";
+    },
     credentialsToEnvironment(creds) {
         const environment = {};
         const data = creds.data;

package/dist/auth/agents/copilot.js

@@ -6,6 +6,7 @@
  */
 import path from "node:path";
 import { extractCredsFromDirectory } from "../extract-creds-from-directory.js";
+import { isCredentialExpired, isTokenExpired } from "../is-token-expired.js";
 import { resolveCustomDirectory } from "../validate-directories.js";
 import { findFirstAvailableToken } from "./copilot-auth-check.js";
 import { CREDS_FILE_NAME, installCopilotCredentials, } from "./copilot-install.js";
@@ -109,6 +110,20 @@ const copilotAdapter = {
         }
         return undefined;
     },
+    isExpired(creds, bufferSeconds = 60) {
+        const token = typeof creds.data.accessToken === "string"
+            ? creds.data.accessToken
+            : undefined;
+        if (token) {
+            const expired = isTokenExpired(token, bufferSeconds);
+            if (expired !== undefined)
+                return expired;
+        }
+        return isCredentialExpired(creds.data, bufferSeconds);
+    },
+    isRefreshable() {
+        return false;
+    },
     credentialsToEnvironment(creds) {
         const environment = {};
         const data = creds.data;

package/dist/auth/agents/gemini.js

@@ -5,6 +5,7 @@
  */
 import path from "node:path";
 import { extractCredsFromDirectory } from "../extract-creds-from-directory.js";
+import { isCredentialExpired, isTokenExpired } from "../is-token-expired.js";
 import { checkEnvironmentAuth, findCredentials } from "./gemini-auth-check.js";
 import { installOAuthCredentials, removeGeminiCredentials, } from "./gemini-install.js";
 const AGENT_ID = "gemini";
@@ -91,6 +92,26 @@ const geminiAdapter = {
         }
         return undefined;
     },
+    isExpired(creds, bufferSeconds = 60) {
+        const data = creds.data;
+        const token = (creds.type === "api-key" && typeof data.apiKey === "string"
+            ? data.apiKey
+            : undefined) ??
+            (creds.type === "oauth-credentials" &&
+                typeof data.access_token === "string"
+                ? data.access_token
+                : undefined);
+        if (token) {
+            const expired = isTokenExpired(token, bufferSeconds);
+            if (expired !== undefined)
+                return expired;
+        }
+        return isCredentialExpired(data, bufferSeconds);
+    },
+    isRefreshable(creds) {
+        return (creds.type === "oauth-credentials" &&
+            typeof creds.data.refresh_token === "string");
+    },
     credentialsToEnvironment(creds) {
         const environment = {};
         const data = creds.data;

package/dist/auth/agents/opencode.js

@@ -8,6 +8,7 @@
  * - Data (auth): ~/.local/share/opencode (XDG_DATA_HOME/opencode)
  */
 import path from "node:path";
+import { isCredentialExpired, isTokenExpired } from "../is-token-expired.js";
 import { extractTokenFromEntry, OpenCodeAuth } from "./opencode-schema.js";
 import { AGENT_ID, CREDS_FILE_NAME, getDefaultAuthFilePath, mapToCredentialType, readAuthFile, } from "./opencode-credentials.js";
 import { installCredentials, removeCredentials } from "./opencode-storage.js";
@@ -122,6 +123,21 @@ const opencodeAdapter = {
             return undefined;
         return extractTokenFromEntry(parsed.data);
     },
+    isExpired(creds, bufferSeconds = 60) {
+        const parsed = OpenCodeAuth.safeParse(creds.data);
+        if (!parsed.success)
+            return undefined;
+        if (parsed.data.type !== "oauth")
+            return undefined;
+        const tokenExpired = isTokenExpired(parsed.data.access, bufferSeconds);
+        if (tokenExpired !== undefined)
+            return tokenExpired;
+        return isCredentialExpired({ expires: parsed.data.expires }, bufferSeconds);
+    },
+    isRefreshable(creds) {
+        const parsed = OpenCodeAuth.safeParse(creds.data);
+        return parsed.success && parsed.data.type === "oauth";
+    },
     credentialsToEnvironment() {
         // OpenCode requires auth.json file, no env var support
         return {};

package/dist/auth/get-access-token-with-refresh.d.ts

@@ -0,0 +1,12 @@
+import type { AgentCli } from "axshared";
+import type { AuthAdapter, FindStoredCredentialsOptions, InstallOptions, OperationResult, TokenOptions } from "./adapter.js";
+import type { Credentials } from "./types.js";
+interface AccessTokenDependencies {
+    adapter: AuthAdapter;
+    installCredentials: (agentId: AgentCli, creds: Credentials, options?: InstallOptions) => OperationResult;
+}
+declare function findCredentialsWithEnvironmentPriority(adapter: AuthAdapter, options?: FindStoredCredentialsOptions): Credentials | undefined;
+type AccessTokenGetter = (agentId: AgentCli, creds: Credentials, options?: TokenOptions) => Promise<string | undefined>;
+declare function getAgentAccessTokenFromStoredCredentials(agentId: AgentCli, adapter: AuthAdapter, options: TokenOptions | undefined, getAccessToken: AccessTokenGetter): Promise<string | undefined>;
+declare function getAccessTokenWithRefresh(agentId: AgentCli, creds: Credentials, options: TokenOptions | undefined, dependencies: AccessTokenDependencies): Promise<string | undefined>;
+export { findCredentialsWithEnvironmentPriority, getAccessTokenWithRefresh, getAgentAccessTokenFromStoredCredentials, };

package/dist/auth/get-access-token-with-refresh.js

@@ -0,0 +1,44 @@
+import { refreshAndPersist } from "./refresh-credentials.js";
+function findCredentialsWithEnvironmentPriority(adapter, options) {
+    const environmentCredentials = adapter.getEnvironmentCredentials?.();
+    if (environmentCredentials)
+        return environmentCredentials;
+    const stored = adapter.findStoredCredentials(options);
+    return stored?.credentials;
+}
+function shouldRefreshToken(adapter, creds, options) {
+    if (creds.type === "api-key")
+        return false;
+    if (options?.skipRefresh)
+        return false;
+    if (!adapter.isRefreshable(creds))
+        return false;
+    return adapter.isExpired(creds) === true;
+}
+async function getAgentAccessTokenFromStoredCredentials(agentId, adapter, options, getAccessToken) {
+    const stored = adapter.findStoredCredentials({
+        provider: options?.provider,
+    });
+    if (!stored)
+        return undefined;
+    return getAccessToken(agentId, stored.credentials, {
+        ...options,
+        storage: options?.storage ?? stored.source,
+    });
+}
+async function getAccessTokenWithRefresh(agentId, creds, options, dependencies) {
+    const token = dependencies.adapter.getAccessToken(creds, options);
+    if (!token)
+        return undefined;
+    if (!shouldRefreshToken(dependencies.adapter, creds, options)) {
+        return token;
+    }
+    const result = await refreshAndPersist(agentId, creds, (resolvedAgentId, refreshedCreds, installOptions) => dependencies.installCredentials(resolvedAgentId, refreshedCreds, installOptions), {
+        timeout: options?.refreshTimeout,
+        provider: options?.provider,
+        storage: options?.storage,
+    });
+    const finalCreds = result.ok ? result.credentials : result.staleCredentials;
+    return dependencies.adapter.getAccessToken(finalCreds, options);
+}
+export { findCredentialsWithEnvironmentPriority, getAccessTokenWithRefresh, getAgentAccessTokenFromStoredCredentials, };

package/dist/auth/is-token-expired.js

@@ -18,18 +18,15 @@
  */
 const SECONDS_THRESHOLD = 10_000_000_000;
 /**
- * Check if a JWT token is expired.
- *
- * Decodes the JWT payload and checks the `exp` claim against current time.
+ * Extract the `exp` claim from a JWT as milliseconds.
  *
- * @param token - The JWT token string
- * @param bufferSeconds - Buffer before actual expiry (default: 60s)
- * @returns true if expired, false if valid, undefined if not a valid JWT
+ * Decodes the base64url payload and reads the `exp` field (seconds -> ms).
+ * Returns undefined if the string is not a valid JWT or has no `exp` claim.
  */
-function isTokenExpired(token, bufferSeconds = 60) {
+function jwtExpiryMs(token) {
     const parts = token.split(".");
     if (parts.length !== 3)
-        return undefined; // Not a JWT
+        return undefined;
     const payloadPart = parts[1];
     if (!payloadPart)
         return undefined;
@@ -40,14 +37,30 @@ function isTokenExpired(token, bufferSeconds = 60) {
         const payload = JSON.parse(atob(padded));
         const exp = payload.exp;
         if (typeof exp !== "number")
-            return undefined; // No exp claim
-        const nowSeconds = Date.now() / 1000;
-        return nowSeconds > exp - bufferSeconds;
+            return undefined;
+        return exp * 1000;
     }
     catch {
-        return undefined; // Invalid JWT
+        return undefined;
     }
 }
+/**
+ * Check if a JWT token is expired.
+ *
+ * Decodes the JWT payload and checks the `exp` claim against current time.
+ *
+ * @param token - The JWT token string
+ * @param bufferSeconds - Buffer before actual expiry (default: 60s)
+ * @returns true if expired, false if valid, undefined if not a valid JWT
+ */
+function isTokenExpired(token, bufferSeconds = 60) {
+    const expiryMs = jwtExpiryMs(token);
+    if (expiryMs === undefined)
+        return undefined;
+    const nowMs = Date.now();
+    const bufferMs = bufferSeconds * 1000;
+    return nowMs > expiryMs - bufferMs;
+}
 /**
  * Check if credentials have expired using explicit timestamp fields.
  *
@@ -103,6 +116,13 @@ function extractExpiryTimestamp(data) {
             ? data.expires * 1000
             : data.expires;
     }
+    // JWT fallback: decode flat access_token for exp claim.
+    const accessToken = typeof data.access_token === "string" ? data.access_token : undefined;
+    if (accessToken !== undefined) {
+        const expMs = jwtExpiryMs(accessToken);
+        if (expMs !== undefined)
+            return expMs;
+    }
     return undefined;
 }
 /**

package/dist/auth/registry.js

@@ -9,9 +9,8 @@ import { codexAdapter } from "./agents/codex.js";
 import { copilotAdapter } from "./agents/copilot.js";
 import { geminiAdapter } from "./agents/gemini.js";
 import { opencodeAdapter } from "./agents/opencode.js";
+import { findCredentialsWithEnvironmentPriority, getAccessTokenWithRefresh, getAgentAccessTokenFromStoredCredentials, } from "./get-access-token-with-refresh.js";
 import { installCredentialsFromEnvironmentCore } from "./install-from-environment.js";
-import { isCredentialExpired, isTokenExpired } from "./is-token-expired.js";
-import { refreshAndPersist } from "./refresh-credentials.js";
 /** Registry of all adapters by agent ID */
 const ADAPTERS = {
     claude: claudeCodeAdapter,
@@ -92,14 +91,7 @@ function checkAllAuth() {
  * const creds = findCredentials("opencode", { provider: "anthropic" });
  */
 function findCredentials(agentId, options) {
-    const adapter = ADAPTERS[agentId];
-    // Check environment credentials first (allows easy overrides in CI/CD)
-    const environmentCredentials = adapter.getEnvironmentCredentials?.();
-    if (environmentCredentials)
-        return environmentCredentials;
-    // Fall back to stored credentials (keychain/file)
-    const stored = adapter.findStoredCredentials(options);
-    return stored?.credentials;
+    return findCredentialsWithEnvironmentPriority(ADAPTERS[agentId], options);
 }
 /**
  * Extract raw credentials from custom directories.
@@ -158,32 +150,10 @@ function removeCredentials(agentId, options) {
  * const token = await getAccessToken(creds, { skipRefresh: true });
  */
 async function getAccessToken(agentId, creds, options) {
-    const token = ADAPTERS[agentId].getAccessToken(creds, options);
-    // No token found
-    if (!token)
-        return undefined;
-    // API keys don't expire
-    if (creds.type === "api-key")
-        return token;
-    // Skip refresh if requested
-    if (options?.skipRefresh)
-        return token;
-    // Check if token is expired (try JWT first, then credential fields)
-    let expired = isTokenExpired(token);
-    if (expired === undefined) {
-        // Token isn't a JWT - check credential's explicit expiry fields
-        expired = isCredentialExpired(creds.data);
-    }
-    if (expired !== true)
-        return token; // Valid or no expiry info
-    // Refresh and persist
-    const result = await refreshAndPersist(agentId, creds, (aid, c, installOptions) => installCredentials(aid, c, installOptions), {
-        timeout: options?.refreshTimeout,
-        provider: options?.provider,
-        storage: options?.storage,
+    return getAccessTokenWithRefresh(agentId, creds, options, {
+        adapter: ADAPTERS[agentId],
+        installCredentials,
     });
-    const finalCreds = result.ok ? result.credentials : result.staleCredentials;
-    return ADAPTERS[agentId].getAccessToken(finalCreds, options);
 }
 /**
  * Get access token for an agent by ID.
@@ -196,16 +166,7 @@ async function getAccessToken(agentId, creds, options) {
  * const token = await getAgentAccessToken("claude");
  */
 async function getAgentAccessToken(agentId, options) {
-    const stored = ADAPTERS[agentId].findStoredCredentials({
-        provider: options?.provider,
-    });
-    if (!stored)
-        return undefined;
-    // Pass the source to getAccessToken so refresh preserves storage location
-    return getAccessToken(agentId, stored.credentials, {
-        ...options,
-        storage: options?.storage ?? stored.source,
-    });
+    return getAgentAccessTokenFromStoredCredentials(agentId, ADAPTERS[agentId], options, getAccessToken);
 }
 /**
  * Convert credentials to environment variables.

package/dist/cli.js

@@ -9,7 +9,8 @@ import packageJson from "../package.json" with { type: "json" };
 import { handleAuthExport, handleAuthInstall, handleAuthList, handleAuthRemove, handleAuthToken, } from "./commands/auth.js";
 import { handleDecrypt } from "./commands/decrypt.js";
 import { handleEncrypt } from "./commands/encrypt.js";
-import { handleVaultFetch, handleVaultPush } from "./commands/vault.js";
+import { handleVaultFetch } from "./commands/vault-fetch.js";
+import { handleVaultPush } from "./commands/vault-push.js";
 import { AGENT_CLIS } from "axshared";
 // Handle SIGINT gracefully
 process.on("SIGINT", () => {
@@ -198,6 +199,8 @@ vault
     .requiredOption("-a, --agent <agent>", `Agent to push credentials from (${AGENT_CLIS.join(", ")})`)
     .requiredOption("-n, --name <name>", "Credential name in vault (e.g., ci, prod)")
     .option("-p, --provider <provider>", "Provider to push (opencode only; pushes single provider instead of all)")
+    .option("--display-name <name>", "Human-readable display name for this credential (e.g., 'Claude (Work)')")
+    .option("--notes <text>", "Additional notes about this credential")
     .addHelpText("after", String.raw `
 Environment variables (option 1 - single JSON):
   AXVAULT           JSON config: {"url":"...","apiKey":"..."}
@@ -210,6 +213,9 @@ Examples:
   # Push local Claude credentials to vault as "ci"
   axauth vault push --agent claude --name ci
 
+  # Push with a display name for multi-instance identification
+  axauth vault push --agent claude --name work-claude --display-name "Claude (Work)"
+
   # Push a single OpenCode provider to vault
   axauth vault push --agent opencode --provider anthropic --name ci-anthropic
 

package/dist/commands/vault-failure-messages.d.ts

@@ -0,0 +1,4 @@
+import type { VaultFailureReason } from "../vault/vault-client.js";
+/** Human-readable error messages for vault failures */
+declare const FAILURE_MESSAGES: Record<VaultFailureReason, string>;
+export { FAILURE_MESSAGES };

package/dist/commands/vault-failure-messages.js

@@ -0,0 +1,12 @@
+/** Human-readable error messages for vault failures */
+const FAILURE_MESSAGES = {
+    "not-configured": "Vault not configured. Set AXVAULT (JSON) or AXVAULT_URL + AXVAULT_API_KEY.",
+    unreachable: "Vault server is unreachable. Check vault URL and network.",
+    unauthorized: "Invalid API key. Check apiKey in vault config.",
+    forbidden: "Access denied. API key doesn't have required access to this credential.",
+    "not-found": "Credential not found in vault.",
+    "legacy-credential": "Credential uses legacy encryption. Re-upload it to vault.",
+    "client-error": "Invalid request. Check credential name and try again.",
+    "server-error": "Vault server error. Check server logs.",
+};
+export { FAILURE_MESSAGES };

package/dist/commands/{vault.d.ts → vault-fetch.d.ts}

@@ -1,5 +1,5 @@
 /**
- * Vault commands - fetch and push credentials to axvault server.
+ * Vault fetch command - download credentials from axvault server.
  */
 interface VaultFetchOptions {
     agent: string;
@@ -19,17 +19,4 @@ interface VaultFetchOptions {
  * - Outputs shell export commands with --env flag (for eval/source)
  */
 declare function handleVaultFetch(options: VaultFetchOptions): Promise<void>;
-interface VaultPushOptions {
-    agent: string;
-    name: string;
-    provider?: string;
-}
-/**
- * Handle vault push command.
- *
- * Reads local credentials for an agent and pushes them to the vault server
- * in raw (unencrypted) format. This allows the vault to handle encryption
- * and automatic token refresh.
- */
-declare function handleVaultPush(options: VaultPushOptions): Promise<void>;
-export { handleVaultFetch, handleVaultPush };
+export { handleVaultFetch };

package/dist/commands/{vault.js → vault-fetch.js}

@@ -1,22 +1,11 @@
 /**
- * Vault commands - fetch and push credentials to axvault server.
+ * Vault fetch command - download credentials from axvault server.
  */
-import { credentialsToEnvironment, findCredentials, installCredentials, } from "../auth/registry.js";
-import { getStoredCredentialsForProvider } from "../auth/agents/opencode.js";
-import { fetchVaultCredentials, pushVaultCredentials, } from "../vault/vault-client.js";
+import { credentialsToEnvironment, installCredentials, } from "../auth/registry.js";
+import { fetchVaultCredentials } from "../vault/vault-client.js";
 import { getVaultConfig } from "../vault/vault-config.js";
+import { FAILURE_MESSAGES } from "./vault-failure-messages.js";
 import { validateAgent } from "./validate-agent.js";
-/** Human-readable error messages for vault failures */
-const FAILURE_MESSAGES = {
-    "not-configured": "Vault not configured. Set AXVAULT (JSON) or AXVAULT_URL + AXVAULT_API_KEY.",
-    unreachable: "Vault server is unreachable. Check vault URL and network.",
-    unauthorized: "Invalid API key. Check apiKey in vault config.",
-    forbidden: "Access denied. API key doesn't have read access to this credential.",
-    "not-found": "Credential not found in vault.",
-    "legacy-credential": "Credential uses legacy encryption. Re-upload it to vault.",
-    "client-error": "Invalid request. Check credential name and try again.",
-    "server-error": "Vault server error. Check server logs.",
-};
 /**
  * Escape a value for safe use in shell export statement.
  * Uses single quotes and escapes any single quotes in the value.
@@ -66,7 +55,7 @@ async function handleVaultFetch(options) {
         process.exitCode = 1;
         return;
     }
-    const { credentials, refreshed } = result;
+    const { credentials, refreshed, displayName, notes } = result;
     // Log refresh status to stderr (not stdout, to allow piping)
     if (refreshed) {
         console.error("Note: Credentials were auto-refreshed by vault");
@@ -112,71 +101,18 @@ async function handleVaultFetch(options) {
     }
     else {
         // Output credentials as JSON (default)
+        const output = {
+            ...credentials,
+            ...(displayName !== undefined && { displayName }),
+            ...(notes !== undefined && { notes }),
+        };
         if (options.json) {
-            console.log(JSON.stringify(credentials, undefined, 2));
+            console.log(JSON.stringify(output, undefined, 2));
         }
         else {
             // Compact JSON for piping
-            console.log(JSON.stringify(credentials));
+            console.log(JSON.stringify(output));
         }
     }
 }
-/**
- * Handle vault push command.
- *
- * Reads local credentials for an agent and pushes them to the vault server
- * in raw (unencrypted) format. This allows the vault to handle encryption
- * and automatic token refresh.
- */
-async function handleVaultPush(options) {
-    // Validate agent
-    const agentId = validateAgent(options.agent);
-    if (!agentId)
-        return;
-    // Validate provider flag usage
-    if (options.provider && agentId !== "opencode") {
-        console.error("Error: --provider flag is only supported for opencode agent");
-        process.exitCode = 2;
-        return;
-    }
-    if (agentId === "opencode" && !options.provider) {
-        console.error("Error: --provider is required for opencode");
-        console.error("Hint: Use 'axauth list --json' to see available providers");
-        process.exitCode = 1;
-        return;
-    }
-    // Check vault is configured
-    const vaultConfig = getVaultConfig();
-    if (!vaultConfig) {
-        console.error(`Error: ${FAILURE_MESSAGES["not-configured"]}`);
-        process.exitCode = 1;
-        return;
-    }
-    // Extract local credentials
-    const credentials = agentId === "opencode" && options.provider
-        ? getStoredCredentialsForProvider(options.provider)
-        : findCredentials(agentId);
-    if (!credentials) {
-        const hint = agentId === "opencode"
-            ? `No credentials found for provider '${options.provider}'`
-            : `No credentials found for ${agentId}\nHint: Authenticate with the agent first, or use 'axauth list' to check status`;
-        console.error(`Error: ${hint}`);
-        process.exitCode = 1;
-        return;
-    }
-    // Push to vault
-    const result = await pushVaultCredentials({
-        agentId,
-        name: options.name,
-        credentials,
-        provider: options.provider,
-    });
-    if (!result.ok) {
-        console.error(`Error: ${FAILURE_MESSAGES[result.reason]}`);
-        process.exitCode = 1;
-        return;
-    }
-    const label = options.provider ? `${agentId}/${options.provider}` : agentId;
-    console.error(`Credentials pushed to vault: ${label} → ${options.name}`);
-}
-export { handleVaultFetch, handleVaultPush };
+export { handleVaultFetch };

package/dist/commands/vault-push.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Vault push command - upload local credentials to axvault server.
+ */
+interface VaultPushOptions {
+    agent: string;
+    name: string;
+    provider?: string;
+    displayName?: string;
+    notes?: string;
+}
+/**
+ * Handle vault push command.
+ *
+ * Reads local credentials for an agent and pushes them to the vault server
+ * in raw (unencrypted) format. This allows the vault to handle encryption
+ * and automatic token refresh.
+ */
+declare function handleVaultPush(options: VaultPushOptions): Promise<void>;
+export { handleVaultPush };

package/dist/commands/vault-push.js

@@ -0,0 +1,70 @@
+/**
+ * Vault push command - upload local credentials to axvault server.
+ */
+import { findCredentials } from "../auth/registry.js";
+import { getStoredCredentialsForProvider } from "../auth/agents/opencode.js";
+import { pushVaultCredentials } from "../vault/vault-client.js";
+import { getVaultConfig } from "../vault/vault-config.js";
+import { FAILURE_MESSAGES } from "./vault-failure-messages.js";
+import { validateAgent } from "./validate-agent.js";
+/**
+ * Handle vault push command.
+ *
+ * Reads local credentials for an agent and pushes them to the vault server
+ * in raw (unencrypted) format. This allows the vault to handle encryption
+ * and automatic token refresh.
+ */
+async function handleVaultPush(options) {
+    // Validate agent
+    const agentId = validateAgent(options.agent);
+    if (!agentId)
+        return;
+    // Validate provider flag usage
+    if (options.provider && agentId !== "opencode") {
+        console.error("Error: --provider flag is only supported for opencode agent");
+        process.exitCode = 2;
+        return;
+    }
+    if (agentId === "opencode" && !options.provider) {
+        console.error("Error: --provider is required for opencode");
+        console.error("Hint: Use 'axauth list --json' to see available providers");
+        process.exitCode = 1;
+        return;
+    }
+    // Check vault is configured
+    const vaultConfig = getVaultConfig();
+    if (!vaultConfig) {
+        console.error(`Error: ${FAILURE_MESSAGES["not-configured"]}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Extract local credentials
+    const credentials = agentId === "opencode" && options.provider
+        ? getStoredCredentialsForProvider(options.provider)
+        : findCredentials(agentId);
+    if (!credentials) {
+        const hint = agentId === "opencode"
+            ? `No credentials found for provider '${options.provider}'`
+            : `No credentials found for ${agentId}\nHint: Authenticate with the agent first, or use 'axauth list' to check status`;
+        console.error(`Error: ${hint}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Push to vault
+    const result = await pushVaultCredentials({
+        agentId,
+        name: options.name,
+        credentials,
+        provider: options.provider,
+        displayName: options.displayName,
+        notes: options.notes,
+    });
+    if (!result.ok) {
+        console.error(`Error: ${FAILURE_MESSAGES[result.reason]}`);
+        process.exitCode = 1;
+        return;
+    }
+    const label = options.provider ? `${agentId}/${options.provider}` : agentId;
+    console.error(`Credentials pushed to vault: ${label} → ${options.name}`);
+}
+export { handleVaultPush };

package/dist/vault/vault-client.d.ts

@@ -14,6 +14,8 @@ type VaultResult = {
     ok: true;
     credentials: Credentials;
     refreshed: boolean;
+    displayName: string | undefined;
+    notes: string | undefined;
 } | {
     ok: false;
     reason: VaultFailureReason;
@@ -61,6 +63,10 @@ interface VaultPushOptions {
     credentials: Credentials;
     /** Provider for multi-provider agents (e.g., "anthropic" for OpenCode) */
     provider?: string;
+    /** Human-readable display name for this credential */
+    displayName?: string;
+    /** Additional notes about this credential */
+    notes?: string;
 }
 /**
  * Push credentials to the axvault server.

package/dist/vault/vault-client.js

@@ -11,6 +11,14 @@ import { getVaultConfig } from "./vault-config.js";
 const VaultCredentialResponse = z.object({
     name: z.string(),
     credential: z.record(z.string(), z.unknown()),
+    displayName: z
+        .string()
+        .nullish()
+        .transform((value) => value ?? undefined),
+    notes: z
+        .string()
+        .nullish()
+        .transform((value) => value ?? undefined),
     updatedAt: z.string(),
 });
 /**
@@ -84,6 +92,8 @@ async function fetchVaultCredentials(options) {
             ok: true,
             credentials: body.credential,
             refreshed: wasRefreshed,
+            displayName: body.displayName,
+            notes: body.notes,
         };
     }
     catch {
@@ -133,6 +143,10 @@ async function pushVaultCredentials(options) {
                 type: options.credentials.type,
                 data: options.credentials.data,
                 ...(options.provider !== undefined && { provider: options.provider }),
+                ...(options.displayName !== undefined && {
+                    displayName: options.displayName,
+                }),
+                ...(options.notes !== undefined && { notes: options.notes }),
             }),
         });
         // Handle error responses

package/package.json

@@ -2,7 +2,7 @@
   "name": "axauth",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "3.1.6",
+  "version": "3.3.0",
   "description": "Authentication management library and CLI for AI coding agents",
   "repository": {
     "type": "git",
@@ -62,31 +62,31 @@
     "automation",
     "coding-assistant"
   ],
-  "packageManager": "pnpm@10.28.1",
+  "packageManager": "pnpm@10.30.1",
   "engines": {
     "node": ">=22.14.0"
   },
   "dependencies": {
     "@commander-js/extra-typings": "^14.0.0",
-    "@inquirer/password": "^5.0.4",
+    "@inquirer/password": "^5.0.7",
     "axconfig": "^3.6.3",
-    "axexec": "^2.0.0",
+    "axexec": "^2.0.1",
     "axshared": "^5.0.0",
-    "commander": "^14.0.2",
-    "zod": "^4.3.5"
+    "commander": "^14.0.3",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@total-typescript/ts-reset": "^0.6.1",
-    "@types/node": "^25.0.10",
-    "@vitest/coverage-v8": "^4.0.17",
-    "eslint": "^9.39.2",
-    "eslint-config-axkit": "^1.1.0",
+    "@types/node": "^25.3.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^10.0.1",
+    "eslint-config-axkit": "^1.2.1",
     "fta-check": "^1.5.1",
     "fta-cli": "^3.0.0",
-    "knip": "^5.82.1",
+    "knip": "^5.85.0",
     "prettier": "3.8.1",
-    "semantic-release": "^25.0.2",
+    "semantic-release": "^25.0.3",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.17"
+    "vitest": "^4.0.18"
   }
 }