@slothmoney/agent-cli 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.2.0 - 2026-07-23
+
+- Add `auth login`, `auth status`, and `auth logout`.
+- Store PATs in native OS credential storage, separated by API origin.
+- Keep `SLOTH_AGENT_TOKEN` as the highest-precedence option for CI and
+  headless systems.
+- Validate imported PATs before saving and report live authentication status
+  without exposing credentials.
+
 ## 0.1.0 - 2026-07-18
 
 - Publish the first installable Sloth Agent CLI.

package/README.md

@@ -15,22 +15,62 @@ sloth-agent --version
 For a one-off pinned run:
 
 ```bash
-npm exec --yes --package=@slothmoney/agent-cli@0.1.0 -- sloth-agent --help
+npm exec --yes --package=@slothmoney/agent-cli@0.2.0 -- sloth-agent --help
 ```
 
 ## Authenticate
 
 Create a personal access token in Sloth Money under
-**Settings > Developer access**. Load it from your environment or secret
-manager:
+**Settings > Developer access**, then save it in your operating system's
+secure credential store:
+
+```bash
+sloth-agent auth login
+```
+
+The prompt hides the token. The CLI validates it before replacing any
+credential already stored for the selected API origin.
+
+For a non-interactive import, pass the token through stdin or import it from
+the environment:
+
+```bash
+printf '%s' "$SLOTH_AGENT_TOKEN" | sloth-agent auth login --token-stdin
+sloth-agent auth login --from-env
+```
+
+Never put a token in a command argument. For CI and headless systems, keep
+using an environment secret:
 
 ```bash
 export SLOTH_AGENT_TOKEN="sloth_pat_v1_..."
 ```
 
-Do not paste the token into prompts, chat, source control, shared logs, or
-assignment files. The CLI reads the token from the environment, sends it only
-as an HTTPS bearer token, and never stores it.
+`SLOTH_AGENT_TOKEN` always overrides a stored credential.
+
+To migrate from an existing environment-only setup:
+
+```bash
+sloth-agent auth login --from-env
+unset SLOTH_AGENT_TOKEN
+sloth-agent auth status
+sloth-agent categories
+```
+
+Check the active credential with a live API request:
+
+```bash
+sloth-agent auth status
+```
+
+This updates the PAT's `lastUsedAt` value. To remove the local credential:
+
+```bash
+sloth-agent auth logout
+```
+
+Logout does not unset `SLOTH_AGENT_TOKEN` or revoke the PAT. Revoke a PAT
+remotely in **Sloth Money Settings > Developer access**.
 
 ## Commands
 
@@ -94,14 +134,18 @@ set `SLOTH_AGENT_API_BASE_URL=http://localhost:4000` or pass
 `--base-url http://localhost:4000`. Non-local HTTP origins are rejected so a
 token cannot be sent over an unencrypted connection.
 
+Stored credentials are separated by normalized API origin. One credential is
+stored per origin; log out and log in again to switch accounts on the same
+origin.
+
 Command results are JSON on stdout. Diagnostics are written to stderr.
 
 | Exit code | Meaning |
 | --- | --- |
 | `0` | Success |
-| `1` | API, network, response-validation, or partial assignment failure |
-| `2` | Invalid command, option, URL, date, or assignment input |
-| `3` | Missing required configuration |
+| `1` | API, network, credential-store, response-validation, or partial assignment failure |
+| `2` | Invalid command, option, URL, date, auth input, or assignment input |
+| `3` | No credential or native secure storage is unavailable |
 
 Assignment writes are best-effort. A response containing any failed assignment
 returns exit code `1` while preserving the complete API response on stdout.

package/dist/args.js

@@ -122,6 +122,46 @@ function parseTransactions(args) {
 function withBaseUrl(value, baseUrl) {
     return baseUrl === undefined ? value : { ...value, baseUrl };
 }
+function parseAuth(args, baseUrl) {
+    const authCommand = args.shift();
+    if (!authCommand) {
+        throw new UsageError('auth requires login, status, or logout');
+    }
+    if (authCommand === 'login') {
+        let input;
+        for (const argument of args) {
+            if (argument === '--token-stdin') {
+                if (input === 'stdin') {
+                    throw new UsageError('--token-stdin may only be provided once');
+                }
+                if (input === 'environment') {
+                    throw new UsageError('--token-stdin and --from-env are mutually exclusive');
+                }
+                input = 'stdin';
+            }
+            else if (argument === '--from-env') {
+                if (input === 'environment') {
+                    throw new UsageError('--from-env may only be provided once');
+                }
+                if (input === 'stdin') {
+                    throw new UsageError('--token-stdin and --from-env are mutually exclusive');
+                }
+                input = 'environment';
+            }
+            else {
+                throw new UsageError(`Unknown auth login option: ${argument}`);
+            }
+        }
+        return withBaseUrl({ command: 'auth-login', input: input ?? 'prompt' }, baseUrl);
+    }
+    if (authCommand === 'status' || authCommand === 'logout') {
+        if (args.length > 0) {
+            throw new UsageError(`Unknown auth ${authCommand} option: ${args[0]}`);
+        }
+        return withBaseUrl({ command: `auth-${authCommand}` }, baseUrl);
+    }
+    throw new UsageError(`Unknown auth command: ${authCommand}`);
+}
 export function parseArgs(argv) {
     if (argv.includes('--help') || argv.includes('-h'))
         return { command: 'help' };
@@ -131,6 +171,9 @@ export function parseArgs(argv) {
     const command = args.shift();
     if (!command)
         return { command: 'help' };
+    if (command === 'auth') {
+        return parseAuth(args, baseUrl);
+    }
     if (command === 'categories') {
         if (args.length > 0) {
             throw new UsageError(`Unknown categories option: ${args[0]}`);

package/dist/cli.js

@@ -1,14 +1,18 @@
 import fs from 'node:fs';
 import { parseArgs, resolveBaseUrl, } from './args.js';
 import { parseApiResponse, validateAssignmentPayload, } from './contracts.js';
+import { createSystemCredentialStore, secureStorageUnavailableError, } from './credential-store.js';
 import { ApiError, CliError, ConfigError, UsageError, } from './errors.js';
-export const CLI_VERSION = '0.1.0';
+export const CLI_VERSION = '0.2.0';
 const REQUEST_TIMEOUT_MS = 30_000;
 export function usageText() {
     return [
         'Sloth Agent CLI',
         '',
         'Usage:',
+        '  sloth-agent auth login [--token-stdin | --from-env] [--base-url URL]',
+        '  sloth-agent auth status [--base-url URL]',
+        '  sloth-agent auth logout [--base-url URL]',
         '  sloth-agent categories [--base-url URL]',
         '  sloth-agent transactions [--uncategorized[=true|false]] [--limit N]',
         '    [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--q TEXT]',
@@ -26,15 +30,63 @@ export function usageText() {
 function writeJson(write, data) {
     write(`${JSON.stringify(data, null, 2)}\n`);
 }
-function requireToken(environment) {
-    const token = environment.SLOTH_AGENT_TOKEN;
-    if (!token?.trim())
-        throw new ConfigError('SLOTH_AGENT_TOKEN is required');
-    return token;
-}
 function redact(value, token) {
     return token ? value.split(token).join('[REDACTED]') : value;
 }
+function environmentToken(environment) {
+    const token = environment.SLOTH_AGENT_TOKEN;
+    return token?.trim() ? token : undefined;
+}
+async function defaultReadSecret() {
+    const { default: password } = await import('@inquirer/password');
+    return password({
+        message: 'Personal access token:',
+        mask: '*',
+    }, {
+        output: process.stderr,
+    });
+}
+async function defaultReadStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function validateLoginToken(value) {
+    if (!value.startsWith('sloth_pat_v1_') || /\s/.test(value)) {
+        throw new UsageError('Personal access token must use the sloth_pat_v1_ prefix and contain no whitespace');
+    }
+    return value;
+}
+function stripStdinLineEnding(value) {
+    if (value.endsWith('\r\n'))
+        return value.slice(0, -2);
+    if (value.endsWith('\n'))
+        return value.slice(0, -1);
+    return value;
+}
+async function loadCredentialStore(getCredentialStore) {
+    try {
+        return await getCredentialStore();
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw secureStorageUnavailableError();
+    }
+}
+async function resolveCredential(environment, origin, getCredentialStore) {
+    const token = environmentToken(environment);
+    if (token)
+        return { source: 'environment', token };
+    const credentialStore = await loadCredentialStore(getCredentialStore);
+    const storedToken = await credentialStore.get(origin);
+    if (!storedToken) {
+        throw new ConfigError(`No credential found for ${origin}. Run "sloth-agent auth login" or set SLOTH_AGENT_TOKEN.`);
+    }
+    return { source: 'keychain', token: storedToken };
+}
 function readAssignmentFile(filePath) {
     try {
         return JSON.parse(fs.readFileSync(filePath, 'utf8'));
@@ -74,7 +126,7 @@ async function parseHttpResponse(response, token) {
         }
         catch {
             if (response.ok)
-                throw new ApiError('Agent API returned invalid JSON');
+                throw new ApiError('Agent API returned invalid JSON', response.status);
         }
     }
     if (!response.ok) {
@@ -84,10 +136,39 @@ async function parseHttpResponse(response, token) {
             && typeof data.error === 'string')
             ? data.error
             : `Agent API request failed with status ${response.status}`;
-        throw new ApiError(redact(message, token));
+        throw new ApiError(redact(message, token), response.status);
     }
     return data;
 }
+function requestHeaders(token) {
+    return {
+        Accept: 'application/json',
+        Authorization: `Bearer ${token}`,
+        'User-Agent': `sloth-agent/${CLI_VERSION}`,
+    };
+}
+async function validateCredentialRemotely(fetchImplementation, origin, token) {
+    const response = await fetchImplementation(`${origin}/api/agent/v1/categories`, {
+        method: 'GET',
+        headers: requestHeaders(token),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    parseApiResponse('categories', await parseHttpResponse(response, token));
+}
+function maskedTokenSuffix(token) {
+    return token.length > 4 ? `…${token.slice(-4)}` : '…';
+}
+function classifyRemoteStatus(error) {
+    if (error instanceof ApiError) {
+        if (error.status === 401)
+            return 'invalid_or_expired';
+        if (error.status === 402)
+            return 'payment_required';
+        if (error.status === 403)
+            return 'insufficient_scope';
+    }
+    return 'unreachable';
+}
 function hasFailures(value) {
     if (!value || typeof value !== 'object' || !('failed' in value))
         return false;
@@ -96,6 +177,11 @@ function hasFailures(value) {
 export async function runCli(argv = process.argv.slice(2), options = {}) {
     const environment = options.env ?? process.env;
     const fetchImplementation = options.fetch ?? globalThis.fetch;
+    const getCredentialStore = options.getCredentialStore ?? createSystemCredentialStore;
+    const isInteractive = options.isInteractive
+        ?? Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    const readSecret = options.readSecret ?? defaultReadSecret;
+    const readStdin = options.readStdin ?? defaultReadStdin;
     const writeStdout = options.writeStdout ?? ((value) => process.stdout.write(value));
     const writeStderr = options.writeStderr ?? ((value) => process.stderr.write(value));
     let token;
@@ -109,13 +195,72 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             writeStdout(`${CLI_VERSION}\n`);
             return 0;
         }
-        token = requireToken(environment);
         const baseUrl = resolveBaseUrl(environment, parsed.baseUrl);
-        const headers = {
-            Accept: 'application/json',
-            Authorization: `Bearer ${token}`,
-            'User-Agent': `sloth-agent/${CLI_VERSION}`,
-        };
+        if (parsed.command === 'auth-login') {
+            if (parsed.input === 'prompt' && !isInteractive) {
+                throw new UsageError('Interactive login requires a TTY. Use --token-stdin or --from-env.');
+            }
+            let rawToken;
+            if (parsed.input === 'environment') {
+                const tokenFromEnvironment = environmentToken(environment);
+                if (!tokenFromEnvironment) {
+                    throw new ConfigError('SLOTH_AGENT_TOKEN is required with --from-env');
+                }
+                rawToken = tokenFromEnvironment;
+            }
+            else {
+                rawToken = await (parsed.input === 'stdin' ? readStdin() : readSecret());
+                if (parsed.input === 'stdin')
+                    rawToken = stripStdinLineEnding(rawToken);
+            }
+            token = validateLoginToken(rawToken);
+            await validateCredentialRemotely(fetchImplementation, baseUrl, token);
+            const credentialStore = await loadCredentialStore(getCredentialStore);
+            await credentialStore.set(baseUrl, token);
+            const environmentOverrideActive = environmentToken(environment) !== undefined;
+            writeJson(writeStdout, {
+                activeSource: environmentOverrideActive ? 'environment' : 'keychain',
+                environmentOverrideActive,
+                origin: baseUrl,
+                stored: true,
+            });
+            return 0;
+        }
+        if (parsed.command === 'auth-status') {
+            const credential = await resolveCredential(environment, baseUrl, getCredentialStore);
+            token = credential.token;
+            let remoteStatus = 'valid';
+            let exitCode = 0;
+            try {
+                await validateCredentialRemotely(fetchImplementation, baseUrl, token);
+            }
+            catch (error) {
+                remoteStatus = classifyRemoteStatus(error);
+                exitCode = 1;
+            }
+            writeJson(writeStdout, {
+                origin: baseUrl,
+                remoteStatus,
+                source: credential.source,
+                tokenSuffix: maskedTokenSuffix(token),
+            });
+            return exitCode;
+        }
+        if (parsed.command === 'auth-logout') {
+            const credentialStore = await loadCredentialStore(getCredentialStore);
+            const localCredentialRemoved = await credentialStore.delete(baseUrl);
+            writeJson(writeStdout, {
+                environmentOverrideActive: environmentToken(environment) !== undefined,
+                localCredentialRemoved,
+                origin: baseUrl,
+                remoteRevoked: false,
+                revocationInstructions: 'Revoke the token in Sloth Money Settings > Developer access.',
+            });
+            return 0;
+        }
+        const credential = await resolveCredential(environment, baseUrl, getCredentialStore);
+        token = credential.token;
+        const headers = requestHeaders(token);
         if (parsed.command === 'assign') {
             const payload = validateAssignmentPayload(readAssignmentFile(parsed.input));
             const endpoint = `${baseUrl}/api/agent/v1/transaction-assignments`;

package/dist/credential-store.js

@@ -0,0 +1,43 @@
+import { ApiError, ConfigError, } from './errors.js';
+const KEYCHAIN_SERVICE = 'app.slothmoney.agent-cli';
+export function secureStorageUnavailableError() {
+    return new ConfigError('Native secure credential storage is unavailable. Set SLOTH_AGENT_TOKEN instead.');
+}
+export async function createSystemCredentialStore() {
+    let keytar;
+    try {
+        const module = await import('@github/keytar');
+        keytar = ('default' in module
+            ? module.default
+            : module);
+    }
+    catch {
+        throw secureStorageUnavailableError();
+    }
+    return {
+        delete: async (origin) => {
+            try {
+                return await keytar.deletePassword(KEYCHAIN_SERVICE, origin);
+            }
+            catch {
+                throw new ApiError('Failed to delete the credential from native secure storage');
+            }
+        },
+        get: async (origin) => {
+            try {
+                return await keytar.getPassword(KEYCHAIN_SERVICE, origin);
+            }
+            catch {
+                throw secureStorageUnavailableError();
+            }
+        },
+        set: async (origin, token) => {
+            try {
+                await keytar.setPassword(KEYCHAIN_SERVICE, origin, token);
+            }
+            catch {
+                throw new ApiError('Failed to save the credential to native secure storage');
+            }
+        },
+    };
+}

package/dist/errors.js

@@ -16,7 +16,9 @@ export class ConfigError extends CliError {
     }
 }
 export class ApiError extends CliError {
-    constructor(message) {
+    status;
+    constructor(message, status) {
         super(message, 1);
+        this.status = status;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slothmoney/agent-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Command-line access to the Sloth Money Agent API.",
   "type": "module",
   "bin": {
@@ -50,5 +50,9 @@
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.35.1",
     "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "@github/keytar": "7.10.6",
+    "@inquirer/password": "4.0.18"
   }
 }