@almyty/credentials 1.5.0

package/README.md

@@ -0,0 +1,207 @@
+# @almyty/credentials
+
+Add a key, a token or a sign-in to almyty once, from your terminal; agents,
+APIs, tools, models, deployments, memory backends, MCP servers, channels and
+registries then use the credential. Model providers, deployment clouds,
+buckets, chat platforms: all of them are services in the same catalog.
+
+```sh
+npx @almyty/auth login
+npx @almyty/credentials services --kind inference
+npx @almyty/credentials add openrouter --open
+npx @almyty/credentials list
+```
+
+## What a credential is
+
+A credential is a row with its service, an account label and a health
+status. The secret is stored encrypted in almyty's credential store and
+is **never returned**, not even masked. Every module that needs it holds a
+reference, resolved on each use, so a rotation is live on the next call and
+every resolve is audited.
+
+```
+b91c…  openrouter  org   ava@northwind   valid
+3d70…  huggingface user  frane           failed
+    401 invalid credentials
+```
+
+## Commands
+
+Every read command takes `--json` and writes undecorated JSON to stdout.
+
+### Read
+
+| Command | What it does |
+|---|---|
+| `services [--kind k]` | The catalog: what a credential can be added for, and how. `--kind` is one of `inference`, `deployment`, `memory`, `mcp`, `tool_source`, `channel`, `cloud`, `registry` |
+| `list` | Every credential, with its health |
+| `get <id>` | One credential: service, account label, health and when it was checked, scopes, owner — and what to do when the health is not `valid` |
+| `grants <id>` | Who may use this credential |
+
+### Add
+
+| Command | What it does |
+|---|---|
+| `add <service> [--method m] [--owner org\|user\|private] [--name n] [--headless] [--open]` | Add a credential |
+| `complete <key> --state s --code c` | Finish a headless sign-in by pasting the code |
+| `validate <id>` | Re-check against the provider; refreshes health and the account label |
+| `rotate <id> [--headless] [--open]` | Replace the secret in place, so everything using the credential keeps working |
+| `delete <id>` | Revoke at the provider where the service declares a revoke endpoint, then delete |
+
+Each service offers one or more methods, best first, and `add` picks the best
+unless `--method` names another. `services` lists them.
+
+**Sign-in** (OpenRouter and Slack today) is the best path: nothing to paste.
+
+```sh
+npx @almyty/credentials add openrouter --open
+```
+
+On a machine with no browser, ask for the headless flow and the provider shows
+a code:
+
+```sh
+npx @almyty/credentials add openrouter --headless
+# -> Open this URL to continue: https://…
+#    The provider will show you a code. Paste it with:
+#      almyty credentials complete openrouter --state st-… --code <code>
+```
+
+The instructions you get are the ones that will work: a browser flow finishes
+on the callback and says so, rather than pointing you at a `complete` command
+whose state the redirect has already consumed.
+
+**A pasted key** prompts for each field, secrets not echoed, with a link to
+the page where the key is created:
+
+```sh
+npx @almyty/credentials add huggingface --owner user
+# Get a key at: https://huggingface.co/settings/tokens
+# Access token: ······
+```
+
+The key is checked against the provider before it is saved. If the provider
+says no, the credential is kept with a `failed` health and the provider's
+answer, so you fix the key at the provider and `validate` or `rotate` rather
+than starting over.
+
+**Rotate** replaces the secret without touching anything that uses the
+credential. For a pasted key it prompts for the new value; for a sign-in
+service it returns a fresh authorize URL and completing it swaps the key on
+the same credential.
+
+### Share
+
+An organization credential is usable by the organization; a grant widens or
+narrows that to a principal.
+
+| Command | What it does |
+|---|---|
+| `grant <id> --principal user\|team\|role\|agent\|workspace --to <principalId> [--permission use\|manage] [--expires <iso8601>]` | Let a principal use (or manage) a credential |
+| `revoke <id> <grantId>` | Withdraw one grant |
+
+## Org or personal
+
+`--owner org` (the default) makes the credential the organization's: this is
+what agents and deployments use, and it needs `connections:manage` (admin or
+owner). `--owner user` makes it yours, and you can grant it to others.
+`--owner private` makes it yours alone: nobody else sees or uses it, org admins
+included, and it cannot be granted. Free and personal organizations allow
+personal and private credentials by default; paid organizations start with them off until
+an admin turns them on.
+
+## Secrets never travel on argv
+
+`ps` shows every process's arguments to every user on the machine, shell
+history keeps them, and most CI runners echo them. So this tool does not take
+a secret as a flag value.
+
+In order of preference:
+
+1. **A sign-in flow** where the service has one. Nothing is typed at all.
+2. **The prompt**, which is the default: secret fields are read without echo.
+3. **`--input-file <path>`** — the form fields as a JSON object in a file.
+4. **`--input-stdin`** — the same object on stdin.
+
+```sh
+npx @almyty/credentials add channel-telegram --input-file bot.json
+pass show telegram/bot | jq -Rn '{bot_token: input}' \
+  | npx @almyty/credentials add channel-telegram --input-stdin
+```
+
+`--input '<json>'` still works for the fields a service does **not** mark
+secret (a region, a bucket, a phone number) and is refused the moment it
+carries one that is, naming the field and the safe alternatives. The refusal
+never repeats the value.
+
+Unattended runs are handled rather than hung: without a terminal to prompt on,
+`add` and `rotate` say so and name `--input-file` and `--input-stdin`
+instead of reading end-of-file and submitting an empty form. `--input-stdin`
+with a terminal on stdin is refused for the same reason.
+
+## Health, and what to do about it
+
+`validate` exits non-zero unless the health comes back `valid`, so it works in
+a check. Each status has a different next step, and `get` and `validate` print
+it:
+
+| Health | What it means |
+|---|---|
+| `valid` | The provider accepted the credential |
+| `failed` | The provider rejected it. Fix it at the provider, then `rotate` |
+| `expired` | It has expired. `rotate` |
+| `revoked` | It was revoked at the provider. `rotate` |
+| `quota` | The credential is fine; the account is out of quota or rate limited. Rotating would not help |
+| `unknown` | Never checked. Run `validate` |
+
+## Chat channels
+
+Every chat channel is a service like any other, so a Slack, Discord or
+Telegram token is added here instead of pasted into a gateway form:
+
+```sh
+npx @almyty/credentials services --kind channel
+npx @almyty/credentials add channel-slack --open
+npx @almyty/credentials add channel-telegram
+```
+
+The service key is `channel-<gateway type>` with underscores dasherized
+(`channel-whatsapp-cloud`), and the form fields are spelled the way the
+channel adapter reads them, so a channel can use a credential you already
+added. `docs/connections.md` has the table of what each channel needs, where
+to get it, and how it is validated.
+
+## Environment
+
+| Variable | Meaning |
+|---|---|
+| `ALMYTY_TOKEN` | Token override; skips `~/.almyty/credentials.json` |
+| `ALMYTY_URL` | API URL override |
+| `NO_COLOR` | Honoured: this tool never colours its output |
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | success |
+| 1 | unexpected error |
+| 2 | usage error (bad flags, missing argument, unknown command, a secret on argv) |
+| 3 | not authenticated — run `npx @almyty/auth login` |
+| 4 | not found |
+| 5 | the operation ran and failed (a `validate` whose health is not `valid`) |
+
+The same table in every `@almyty/*` CLI.
+
+## About almyty
+
+almyty is the platform for AI agents, agnostic by design: any LLM, any API
+turned into tools, served over MCP, A2A, UTCP and Agent Skills.
+
+- Website: https://almyty.com
+- Design notes: `docs/connections.md` in the almyty repository
+- Source: https://github.com/almyty-inc/almyty
+
+Run `npx @almyty/credentials --help` for the full surface.
+
+Apache-2.0 © Almyty Inc.

package/dist/exit-codes.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Exit codes shared by every almyty CLI.
+ *
+ * Scripts need to tell "you are not logged in" apart from "that card does
+ * not exist" apart from "the validation run failed" without grepping
+ * stderr. Every almyty CLI uses this same table, so
+ * `almyty models validate x || case $? in 3) almyty auth login;; esac`
+ * behaves the same whichever binary produced the code.
+ *
+ * Kept as a copy rather than an import: these CLIs are published
+ * separately and this table is six numbers that must never drift, which a
+ * test in each package pins.
+ */
+export declare const EXIT: {
+    /** Success. */
+    readonly OK: 0;
+    /** Unexpected failure (a thrown error with no better classification). */
+    readonly ERROR: 1;
+    /** Bad or missing arguments, or an unknown command. */
+    readonly USAGE: 2;
+    /** No stored credential, or the API rejected the one we had. */
+    readonly AUTH: 3;
+    /** The named card, deployment, connection or grant does not exist. */
+    readonly NOT_FOUND: 4;
+    /** The command ran; the operation it asked for failed. */
+    readonly FAILED: 5;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+/** One line per code, for `--help` output and READMEs. */
+export declare const EXIT_CODE_HELP: string;
+/** Errors the CLI raises itself for a bad invocation, so they exit 2. */
+export declare class UsageError extends Error {
+}
+/**
+ * Classify a thrown error into an exit code.
+ *
+ * The shared client turns a 401 into "Authentication failed. Run: npx
+ * @almyty/auth login" and everything else into "API error <status>: <body>",
+ * so the status is what there is to go on.
+ */
+export declare function exitCodeFor(err: unknown): ExitCode;
+/**
+ * What to print when a command fails.
+ *
+ * Node's fetch says `fetch failed` and nothing else, which tells the reader
+ * neither which host was unreachable nor that the URL is theirs to change.
+ * Every message here names the next thing to do.
+ */
+export declare function describeError(err: unknown, apiUrl?: string): string;

package/dist/exit-codes.js

@@ -0,0 +1,90 @@
+/**
+ * Exit codes shared by every almyty CLI.
+ *
+ * Scripts need to tell "you are not logged in" apart from "that card does
+ * not exist" apart from "the validation run failed" without grepping
+ * stderr. Every almyty CLI uses this same table, so
+ * `almyty models validate x || case $? in 3) almyty auth login;; esac`
+ * behaves the same whichever binary produced the code.
+ *
+ * Kept as a copy rather than an import: these CLIs are published
+ * separately and this table is six numbers that must never drift, which a
+ * test in each package pins.
+ */
+export const EXIT = {
+    /** Success. */
+    OK: 0,
+    /** Unexpected failure (a thrown error with no better classification). */
+    ERROR: 1,
+    /** Bad or missing arguments, or an unknown command. */
+    USAGE: 2,
+    /** No stored credential, or the API rejected the one we had. */
+    AUTH: 3,
+    /** The named card, deployment, connection or grant does not exist. */
+    NOT_FOUND: 4,
+    /** The command ran; the operation it asked for failed. */
+    FAILED: 5,
+};
+/** One line per code, for `--help` output and READMEs. */
+export const EXIT_CODE_HELP = [
+    '  0  success',
+    '  1  unexpected error',
+    '  2  usage error (bad flags, unknown command)',
+    '  3  not authenticated — run `almyty auth login`',
+    '  4  not found',
+    '  5  the operation ran and failed',
+].join('\n');
+/** Errors the CLI raises itself for a bad invocation, so they exit 2. */
+export class UsageError extends Error {
+}
+/**
+ * Classify a thrown error into an exit code.
+ *
+ * The shared client turns a 401 into "Authentication failed. Run: npx
+ * @almyty/auth login" and everything else into "API error <status>: <body>",
+ * so the status is what there is to go on.
+ */
+export function exitCodeFor(err) {
+    if (err instanceof UsageError)
+        return EXIT.USAGE;
+    const message = err instanceof Error ? err.message : String(err);
+    if (/^--|is required|must be|contradict|nothing to set|unknown command/i.test(message))
+        return EXIT.USAGE;
+    if (/Authentication failed|\bAPI error 401\b|\b403\b/.test(message))
+        return EXIT.AUTH;
+    if (/\bAPI error 404\b/.test(message))
+        return EXIT.NOT_FOUND;
+    if (/\bAPI error 4\d\d\b|\bAPI error 5\d\d\b/.test(message))
+        return EXIT.FAILED;
+    return EXIT.ERROR;
+}
+/**
+ * What to print when a command fails.
+ *
+ * Node's fetch says `fetch failed` and nothing else, which tells the reader
+ * neither which host was unreachable nor that the URL is theirs to change.
+ * Every message here names the next thing to do.
+ */
+export function describeError(err, apiUrl) {
+    const message = err instanceof Error ? err.message : String(err);
+    const where = apiUrl ? ` at ${apiUrl}` : '';
+    if (/Authentication failed|\bAPI error 401\b/.test(message)) {
+        return 'Not authenticated: the stored token is missing or has expired.\n  Run: npx @almyty/auth login   (or set ALMYTY_TOKEN)';
+    }
+    if (/\bAPI error 403\b/.test(message)) {
+        return `${message}\n  The token is valid but lacks permission here. An organization connection needs connections:manage (admin or owner).`;
+    }
+    if (/\bAPI error 404\b/.test(message)) {
+        return `${message}\n  No such id, or it belongs to another organization.`;
+    }
+    if (/ECONNREFUSED|ENOTFOUND|EAI_AGAIN|fetch failed|other side closed|socket hang up/i.test(message)) {
+        return `Could not reach the almyty API${where}: ${message}\n  Check ALMYTY_URL and the network, then try again.`;
+    }
+    if (/certificate|self.signed|SSL/i.test(message)) {
+        return `TLS handshake with the almyty API${where} failed: ${message}`;
+    }
+    if (/ENOENT/.test(message)) {
+        return `${message}\n  The file named by --input-file or --config-file does not exist.`;
+    }
+    return message;
+}

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+export interface ParsedArgs {
+    command?: string;
+    positional: string[];
+    flags: Record<string, string | boolean>;
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/**
+ * A missing id used to be sent to the API as the literal string "undefined",
+ * which came back as an opaque 400. Say what is missing instead.
+ */
+export declare function needArg(positional: string[], index: number, name: string, usage: string): string;
+export declare function connectBody(flags: ParsedArgs['flags'], input?: Record<string, unknown>): Record<string, unknown>;
+export declare function grantBody(flags: ParsedArgs['flags']): Record<string, unknown>;
+/** A JSON object, or a message naming which flag was wrong. */
+export declare function parseInputObject(raw: string, flag: string): Record<string, unknown>;
+export declare function parseInput(flags: ParsedArgs['flags']): Record<string, unknown> | undefined;
+/** Names of the fields a connect form marks `x-secret`. */
+export declare function secretFields(schema: any): string[];
+/**
+ * Refuse a secret that arrived on the command line.
+ *
+ * argv is readable by every process on the machine through `ps`, is written
+ * to shell history, and is echoed by most CI runners. A key that travelled
+ * that way has to be treated as disclosed, so the tool declines rather than
+ * accepting it and storing it as if it were safe.
+ */
+export declare function assertNoArgvSecrets(schema: any, input: Record<string, unknown>): void;
+export declare function isRedirectMethod(type: string): boolean;
+/** browser unless asked for headless; --open only makes sense with a browser. */
+export declare function connectMode(flags: ParsedArgs['flags']): 'browser' | 'headless';
+/**
+ * What to tell the user after a sign-in connect. The backend decides how the
+ * flow finishes and says so in `completeWith`; printing the paste-a-code
+ * instruction for a callback flow sent people to a command that cannot work,
+ * because the state is consumed by the redirect.
+ */
+export declare function pendingRedirectMessage(pending: any, connectorKey: string): string;
+export declare function formatConnector(c: any): string;
+export declare function formatConnection(c: any): string;
+/**
+ * The detail view. `list` is one line per credential; this answers the
+ * question the one-liner cannot: what is wrong with this credential, when
+ * was that last checked, and what may it do.
+ */
+export declare function formatConnectionDetail(c: any): string;
+/** Every health status other than `valid` has a different next step. */
+export declare function healthAdvice(status: string): string;
+export declare function formatGrant(g: any): string;
+/** Pick the method to use: the one asked for, else the connector's best. */
+export declare function chooseMethod(connector: any, wanted?: string): any;
+/**
+ * Reading stdin when stdin is the terminal means waiting for a person to
+ * type JSON and press ctrl-D, which looks exactly like a hang. Say so.
+ */
+export declare function assertStdinIsPiped(flag: string): void;
+/** Why `--input` is refused where the form is not known in advance. */
+export declare function unscreenableInputMessage(): string;
+/**
+ * Prompting needs a terminal. Without one (a pipe, a CI job, a cron) the
+ * prompt used to read end-of-file and submit an empty form, which the
+ * provider then rejected for a reason that had nothing to do with the key.
+ */
+export declare function requireTty(what: string, isTty?: boolean): void;

package/dist/index.js

@@ -0,0 +1,589 @@
+#!/usr/bin/env node
+/**
+ * @almyty/credentials: keys, tokens and accounts from the terminal.
+ *
+ * Credentials are the one place almyty keeps a third-party secret: every
+ * credential is a row with its service, an account label and a health
+ * status, and everything that uses it (agents, APIs, tools, models,
+ * deployments, channels) holds a reference rather than a copy. See
+ * docs/connections.md.
+ *
+ * How a secret reaches the API matters, so this tool never wants one on the
+ * command line: argv is visible in `ps` and lands in shell history and CI
+ * logs. The paths are, best first: the service's sign-in flow (nothing to
+ * paste), a hidden terminal prompt, `--input-file`, or `--input-stdin`.
+ * `--input` stays for non-secret fields and is refused for secret ones.
+ */
+import { createInterface } from 'readline';
+import { readFileSync } from 'fs';
+import { AlmytyClient, resolveCredentialsOrExit } from '@almyty/client';
+import { EXIT, EXIT_CODE_HELP, UsageError, describeError, exitCodeFor } from './exit-codes.js';
+import { VERSION } from './version.js';
+/** Flags that never take a value. */
+const BOOLEAN_FLAGS = new Set(['json', 'open', 'headless', 'input-stdin']);
+export function parseArgs(argv) {
+    const result = { positional: [], flags: {} };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-h') {
+            result.flags.help = true;
+            continue;
+        }
+        if (arg === '-v') {
+            result.flags.version = true;
+            continue;
+        }
+        if (arg === '--') {
+            // Everything after `--` is positional, flags included.
+            result.positional.push(...argv.slice(i + 1));
+            break;
+        }
+        if (arg.startsWith('--')) {
+            const body = arg.slice(2);
+            // `--flag=value` as well as `--flag value`. With only the space form,
+            // `--input='{"a":1}'` became a flag literally named `input={"a":1}`
+            // and the value was dropped without a word.
+            const eq = body.indexOf('=');
+            if (eq !== -1) {
+                result.flags[body.slice(0, eq)] = body.slice(eq + 1);
+                continue;
+            }
+            if (body === 'help' || body === 'version') {
+                result.flags[body] = true;
+                continue;
+            }
+            if (BOOLEAN_FLAGS.has(body)) {
+                result.flags[body] = true;
+                continue;
+            }
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('--')) {
+                result.flags[body] = next;
+                i++;
+            }
+            else
+                result.flags[body] = true;
+            continue;
+        }
+        if (!result.command)
+            result.command = arg;
+        else
+            result.positional.push(arg);
+    }
+    return result;
+}
+function printHelp() {
+    console.log(`
+@almyty/credentials v${VERSION}
+
+Add a key, a token or a sign-in once; agents, APIs, tools, models,
+deployments and channels use the credential. The secret is stored encrypted
+in almyty and is never returned, not even masked.
+
+Usage:
+  npx @almyty/credentials <command> [options]
+
+Read:
+  services [--kind k]                   The services a credential can be added for, and how
+                                        --kind inference|deployment|memory|mcp|tool_source|channel|cloud|registry
+  list                                  Every credential, with whether it works
+  get <id>                              One credential: service, account, health, scopes, owner
+  grants <id>                           Who may use this credential
+
+Add:
+  add <service> [--method m] [--owner org|user|private] [--name n] [--headless] [--open]
+                                        A sign-in prints an authorize URL (--open launches a
+                                        browser, --headless asks the service for a code to paste).
+                                        A key form prompts for each field, secrets not echoed.
+  complete <service> --state s --code c Finish a headless sign-in by pasting the code
+  validate <id>                         Check it with the service again; refreshes health and label.
+                                        Exits non-zero unless the health comes back valid.
+  rotate <id> [--headless] [--open]     Replace the key in place; everything using the
+                                        credential keeps working. Prompts for the new value.
+  delete <id>                           Revoke at the service where it can be, then delete
+
+
+Share:
+  grant <id> --principal user|team|role|agent|workspace --to <principalId>
+             [--permission use|manage] [--expires <iso8601>]
+  revoke <id> <grantId>                 Withdraw one grant
+
+Supplying form fields without a prompt (connect, rotate):
+  --input-file <path>                   Read the fields as a JSON object from a file
+  --input-stdin                         Read the fields as a JSON object from stdin
+  --input '<json>'                      Non-secret fields only. Refused when it carries a field the
+                                        service marks secret, because argv is world-readable.
+
+Options:
+  --json                                Undecorated JSON on stdout, for scripts
+  -h, --help                            This help
+  -v, --version                         Print the version
+
+Environment:
+  ALMYTY_TOKEN                          Token override (skips ~/.almyty/credentials.json)
+  ALMYTY_URL                            API URL override
+  NO_COLOR                              Honoured: this tool never colours its output
+
+Exit codes:
+${EXIT_CODE_HELP}
+`);
+}
+const str = (flags, key) => (typeof flags[key] === 'string' ? flags[key] : undefined);
+const need = (flags, key) => {
+    const v = str(flags, key);
+    if (!v)
+        throw new UsageError(`--${key} is required`);
+    return v;
+};
+/**
+ * A missing id used to be sent to the API as the literal string "undefined",
+ * which came back as an opaque 400. Say what is missing instead.
+ */
+export function needArg(positional, index, name, usage) {
+    const v = positional[index];
+    if (!v)
+        throw new UsageError(`${name} is required\n  usage: almyty credentials ${usage}`);
+    return v;
+}
+export function connectBody(flags, input) {
+    const body = { owner: str(flags, 'owner') ?? 'org' };
+    if (!['org', 'user', 'private'].includes(body.owner))
+        throw new UsageError('--owner must be org, user or private');
+    if (str(flags, 'method'))
+        body.method = str(flags, 'method');
+    if (str(flags, 'name'))
+        body.name = str(flags, 'name');
+    if (input && Object.keys(input).length > 0)
+        body.input = input;
+    return body;
+}
+export function grantBody(flags) {
+    const principalType = need(flags, 'principal');
+    if (!['user', 'team', 'role', 'agent', 'workspace'].includes(principalType))
+        throw new UsageError('--principal must be user, team, role, agent or workspace');
+    const permission = str(flags, 'permission') ?? 'use';
+    if (!['use', 'manage'].includes(permission))
+        throw new UsageError('--permission must be use or manage');
+    const body = { principalType, principalId: need(flags, 'to'), permission };
+    if (str(flags, 'expires'))
+        body.expiresAt = str(flags, 'expires');
+    return body;
+}
+/** A JSON object, or a message naming which flag was wrong. */
+export function parseInputObject(raw, flag) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new UsageError(`${flag} must be valid JSON`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new UsageError(`${flag} must be a JSON object`);
+    return parsed;
+}
+export function parseInput(flags) {
+    const raw = str(flags, 'input');
+    if (!raw)
+        return undefined;
+    try {
+        return parseInputObject(raw, '--input');
+    }
+    catch {
+        throw new UsageError('--input must be a JSON object');
+    }
+}
+/** Names of the fields a connect form marks `x-secret`. */
+export function secretFields(schema) {
+    const props = schema?.properties ?? {};
+    return Object.entries(props).filter(([, def]) => def?.['x-secret'] === true).map(([key]) => key);
+}
+/**
+ * Refuse a secret that arrived on the command line.
+ *
+ * argv is readable by every process on the machine through `ps`, is written
+ * to shell history, and is echoed by most CI runners. A key that travelled
+ * that way has to be treated as disclosed, so the tool declines rather than
+ * accepting it and storing it as if it were safe.
+ */
+export function assertNoArgvSecrets(schema, input) {
+    const offending = secretFields(schema).filter((f) => input[f] !== undefined);
+    if (offending.length === 0)
+        return;
+    throw new UsageError(`${offending.join(', ')} ${offending.length === 1 ? 'is a secret' : 'are secrets'} and --input puts it in your shell history and in \`ps\`.\n` +
+        '  Leave --input off and the field is prompted without echo, or pass the whole object as\n' +
+        '    --input-file <path>   read the JSON object from a file\n' +
+        '    --input-stdin         read the JSON object from stdin');
+}
+/**
+ * The methods that send the user to the provider and finish on the callback,
+ * spelled exactly the way the API spells them (`REDIRECT_METHODS`).
+ * Guessing from the name prefix was wrong for both of the methods whose name
+ * does not match their shape: `oauth2_client_credentials` is a form (a client
+ * id and secret you paste, so it must be prompted) and `installation` is a
+ * redirect that does not start with `oauth2`.
+ */
+const REDIRECT_METHODS = ['oauth2_pkce', 'oauth2_code', 'installation'];
+export function isRedirectMethod(type) {
+    return REDIRECT_METHODS.includes(type);
+}
+/** browser unless asked for headless; --open only makes sense with a browser. */
+export function connectMode(flags) {
+    return flags.headless ? 'headless' : 'browser';
+}
+/**
+ * What to tell the user after a sign-in connect. The backend decides how the
+ * flow finishes and says so in `completeWith`; printing the paste-a-code
+ * instruction for a callback flow sent people to a command that cannot work,
+ * because the state is consumed by the redirect.
+ */
+export function pendingRedirectMessage(pending, connectorKey) {
+    const lines = [`Open this URL to continue:`, pending.authorizeUrl, ''];
+    if (pending.completeWith === 'code') {
+        lines.push('The provider will show you a code. Paste it with:', `  almyty credentials complete ${connectorKey} --state ${pending.state} --code <code>`);
+    }
+    else {
+        lines.push('Approve in the browser and the connect finishes on its own; then:', '  almyty credentials list', '', 'On a machine with no browser, start again with --headless and the provider', 'shows a code you paste into `almyty credentials complete` instead.');
+    }
+    if (pending.expiresInSeconds)
+        lines.push('', `This link expires in ${Math.round(pending.expiresInSeconds / 60)} minutes.`);
+    return lines.join('\n');
+}
+export function formatConnector(c) {
+    const methods = (c.connect ?? []).map((m) => m.type).join(', ');
+    return `${c.key}  ${c.displayName}  [${c.kind}]  ${methods}${c.custom ? '  (custom)' : ''}`;
+}
+export function formatConnection(c) {
+    const health = c.health?.status ?? 'unknown';
+    const label = c.accountLabel ? `  ${c.accountLabel}` : '';
+    const err = c.health?.error ? `\n    ${c.health.error}` : '';
+    return `${c.id}  ${c.connectorKey}  ${c.owner}${label}  ${health}${err}`;
+}
+/**
+ * The detail view. `list` is one line per credential; this answers the
+ * question the one-liner cannot: what is wrong with this credential, when
+ * was that last checked, and what may it do.
+ */
+export function formatConnectionDetail(c) {
+    const lines = [
+        `${c.name ?? c.connectorKey}`,
+        `  id          ${c.id}`,
+        `  service     ${c.connectorKey}${c.connectorDisplayName ? ` (${c.connectorDisplayName})` : ''}${c.kind ? `  [${c.kind}]` : ''}`,
+        `  owner       ${c.owner}${c.ownerUserId ? ` (${c.ownerUserId})` : ''}`,
+        `  method      ${c.method ?? 'unknown'}`,
+        `  account     ${c.accountLabel ?? '(the provider named none)'}`,
+        `  health      ${c.health?.status ?? 'unknown'}${c.health?.checkedAt ? `, checked ${c.health.checkedAt}` : ', never checked'}`,
+    ];
+    if (c.health?.error)
+        lines.push(`  error       ${c.health.error}`);
+    lines.push(`  scopes      ${c.scopesGranted?.length ? c.scopesGranted.join(', ') : '(none reported)'}`);
+    if (c.expiresAt)
+        lines.push(`  expires     ${c.expiresAt}`);
+    if (c.health?.status && c.health.status !== 'valid') {
+        lines.push('', healthAdvice(c.health.status), '', 'The stored secret is never returned, so fix it at the provider and then:', `  almyty credentials rotate ${c.id}`);
+    }
+    return lines.join('\n');
+}
+/** Every health status other than `valid` has a different next step. */
+export function healthAdvice(status) {
+    switch (status) {
+        case 'failed': return 'The provider rejected the stored secret. Re-check it and rotate.';
+        case 'expired': return 'The stored secret has expired. Rotate to replace it.';
+        case 'revoked': return 'The secret was revoked at the provider. Rotate to replace it.';
+        case 'quota': return 'The credential is good but the account is out of quota or over its rate limit at the provider.';
+        case 'unknown': return 'Never checked against the provider. Run `almyty credentials validate <id>`.';
+        default: return `Health is ${status}.`;
+    }
+}
+export function formatGrant(g) {
+    return `${g.id}  ${g.principalType}:${g.principalName ?? g.principalId}  ${g.permission}${g.expiresAt ? `  until ${g.expiresAt}` : ''}`;
+}
+/** Pick the method to use: the one asked for, else the connector's best. */
+export function chooseMethod(connector, wanted) {
+    const methods = connector?.connect ?? [];
+    if (methods.length === 0)
+        throw new UsageError(`${connector?.key ?? 'connector'} has no connect method`);
+    if (!wanted)
+        return methods[0];
+    const found = methods.find((m) => m.type === wanted);
+    if (!found)
+        throw new UsageError(`${connector.key} does not support ${wanted}; available: ${methods.map((m) => m.type).join(', ')}`);
+    return found;
+}
+/** Ask for each schema field at the terminal; x-secret fields are read without echo. */
+async function promptForSchema(schema) {
+    const out = {};
+    const props = schema?.properties ?? {};
+    const required = schema?.required ?? [];
+    for (const [key, def] of Object.entries(props)) {
+        const label = `${def.title ?? key}${required.includes(key) ? '' : ' (optional)'}${def.default !== undefined ? ` [${def.default}]` : ''}: `;
+        const value = await ask(label, Boolean(def['x-secret']));
+        if (value === '' && def.default !== undefined)
+            out[key] = def.default;
+        else if (value !== '')
+            out[key] = def.type === 'integer' || def.type === 'number' ? Number(value) : def.type === 'boolean' ? /^(y|yes|true|1)$/i.test(value) : value;
+    }
+    return out;
+}
+function ask(label, secret) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+        if (secret) {
+            // Hide the typed characters: readline echoes through _writeToOutput.
+            const anyRl = rl;
+            anyRl._writeToOutput = (s) => {
+                if (s.includes(label))
+                    anyRl.output.write(label);
+            };
+        }
+        rl.question(label, (answer) => {
+            rl.close();
+            if (secret)
+                process.stdout.write('\n');
+            resolve(answer.trim());
+        });
+    });
+}
+/**
+ * Reading stdin when stdin is the terminal means waiting for a person to
+ * type JSON and press ctrl-D, which looks exactly like a hang. Say so.
+ */
+export function assertStdinIsPiped(flag) {
+    if (!process.stdin.isTTY)
+        return;
+    throw new UsageError(`${flag} reads stdin, and stdin is your terminal, so it would wait forever.\n` +
+        `  Pipe the JSON in:  cat fields.json | almyty credentials <command> ${flag}\n` +
+        '  Or use --input-file <path>, or leave both off and be prompted.');
+}
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => { data += chunk; });
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', reject);
+    });
+}
+/**
+ * Where the form fields come from, in order of how safely the secret travels:
+ * a file, stdin, then argv (non-secret fields only), then a hidden prompt.
+ * Returns undefined when nothing was supplied and the caller should prompt.
+ */
+async function suppliedInput(flags, schema, 
+/**
+ * False when the form is not known yet, so which fields are secret is not
+ * known either. `rotate` is in that position: the API only answers with
+ * the form after the first call, so `--input` cannot be screened and is
+ * refused outright rather than accepted blind.
+ */
+schemaKnown = true) {
+    const file = str(flags, 'input-file');
+    if (file)
+        return parseInputObject(readFileSync(file, 'utf8'), `--input-file ${file}`);
+    if (flags['input-stdin']) {
+        assertStdinIsPiped('--input-stdin');
+        return parseInputObject(await readStdin(), '--input-stdin');
+    }
+    const inline = parseInput(flags);
+    if (inline) {
+        if (!schemaKnown)
+            throw new UsageError(unscreenableInputMessage());
+        assertNoArgvSecrets(schema, inline);
+        return inline;
+    }
+    return undefined;
+}
+/** Why `--input` is refused where the form is not known in advance. */
+export function unscreenableInputMessage() {
+    return [
+        '--input cannot be used here: which of these fields are secret is only known once the API',
+        'answers with the form, and argv is in your shell history and in `ps`.',
+        '  --input-file <path>   read the JSON object from a file',
+        '  --input-stdin         read the JSON object from stdin',
+        '  or leave both off and the fields are prompted, secrets without echo',
+    ].join('\n');
+}
+/**
+ * Prompting needs a terminal. Without one (a pipe, a CI job, a cron) the
+ * prompt used to read end-of-file and submit an empty form, which the
+ * provider then rejected for a reason that had nothing to do with the key.
+ */
+export function requireTty(what, isTty = process.stdin.isTTY) {
+    if (isTty)
+        return;
+    throw new UsageError(`${what} needs a terminal to prompt on, and stdin is not one.\n` +
+        '  Pass the fields instead:\n' +
+        '    --input-file <path>   read the JSON object from a file\n' +
+        '    --input-stdin         read the JSON object from stdin');
+}
+function newClient() {
+    const creds = resolveCredentialsOrExit();
+    return new AlmytyClient(creds.url, creds.token);
+}
+function out(args, data, pretty) {
+    console.log(args.flags.json ? JSON.stringify(data, null, 2) : pretty());
+}
+async function openInBrowser(url) {
+    const { spawn } = await import('child_process');
+    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+    spawn(cmd, [url], { detached: true, stdio: 'ignore' }).unref();
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.flags.version)
+        return void console.log(VERSION);
+    if (!args.command || args.command === 'help' || args.flags.help)
+        return printHelp();
+    const client = newClient();
+    const q = (path, init) => client.request(path, init);
+    const post = (path, body) => q(path, { method: 'POST', body: JSON.stringify(body) });
+    switch (args.command) {
+        case 'services': {
+            // Filtered by the API, so an unknown kind is an error instead of an
+            // empty list that looks like "nothing can be connected".
+            const kind = str(args.flags, 'kind');
+            const res = await q(`/credentials/services${kind ? `?kind=${encodeURIComponent(kind)}` : ''}`);
+            out(args, res.data, () => (res.data.length ? res.data.map(formatConnector).join('\n') : `No services${kind ? ` of kind ${kind}` : ''}.`));
+            return;
+        }
+        case 'list': {
+            const res = await q('/credentials');
+            out(args, res.data, () => (res.data.length ? res.data.map(formatConnection).join('\n') : 'No credentials yet. Run: almyty credentials services'));
+            return;
+        }
+        case 'get': {
+            const id = needArg(args.positional, 0, 'credential id', 'get <id>');
+            const res = await q(`/credentials/${id}`);
+            out(args, res.data, () => formatConnectionDetail(res.data));
+            return;
+        }
+        case 'add': {
+            const key = needArg(args.positional, 0, 'service key', 'add <service>');
+            const catalog = await q('/credentials/services');
+            const connector = catalog.data.find((c) => c.key === key);
+            if (!connector)
+                throw new UsageError(`unknown service ${key}; run: almyty credentials services`);
+            const method = chooseMethod(connector, str(args.flags, 'method'));
+            const isRedirect = isRedirectMethod(method.type);
+            let input = await suppliedInput(args.flags, method.schema);
+            if (!isRedirect && !input && method.schema) {
+                // `description` is the field the connector catalog actually carries;
+                // `instructions` is kept for custom connectors that use that name.
+                const guidance = method.description ?? method.instructions;
+                if (guidance)
+                    console.log(`\n${guidance}\n`);
+                const keyPage = method.keyPageUrl ?? connector.keyPageUrl;
+                if (keyPage)
+                    console.log(`Get a key at: ${keyPage}`);
+                if (method.quickCreateUrl)
+                    console.log(`Quick create: ${method.quickCreateUrl}`);
+                requireTty(`connect ${key} via ${method.type}`);
+                input = await promptForSchema(method.schema);
+            }
+            const body = connectBody({ ...args.flags, method: method.type }, input);
+            if (isRedirect)
+                body.mode = connectMode(args.flags);
+            const res = await post(`/credentials/connect/${key}`, body);
+            if (res.data?.authorizeUrl) {
+                if (args.flags.json)
+                    console.log(JSON.stringify(res.data, null, 2));
+                else
+                    console.log(pendingRedirectMessage(res.data, key));
+                if (args.flags.open)
+                    await openInBrowser(res.data.authorizeUrl);
+                return;
+            }
+            out(args, res.data, () => `Added.\n${formatConnection(res.data.connection ?? res.data)}`);
+            return;
+        }
+        case 'complete': {
+            const key = needArg(args.positional, 0, 'service key', 'complete <service> --state s --code c');
+            const res = await post(`/credentials/connect/${key}/complete`, { state: need(args.flags, 'state'), code: need(args.flags, 'code') });
+            out(args, res.data, () => `Added.\n${formatConnection(res.data.connection ?? res.data)}`);
+            return;
+        }
+        case 'validate': {
+            const id = needArg(args.positional, 0, 'credential id', 'validate <id>');
+            const res = await post(`/credentials/${id}/validate`, {});
+            const connection = res.data.connection ?? res.data;
+            const status = connection.health?.status ?? 'unknown';
+            out(args, connection, () => (status === 'valid'
+                ? `Valid.\n${formatConnection(connection)}`
+                : `${status}.\n${formatConnection(connection)}\n\n${healthAdvice(status)}`));
+            // A validate that came back failed is a failure. Exiting 0 made this
+            // useless in a script and in a health check.
+            if (status !== 'valid')
+                process.exitCode = EXIT.FAILED;
+            return;
+        }
+        case 'rotate': {
+            const id = needArg(args.positional, 0, 'credential id', 'rotate <id>');
+            const supplied = await suppliedInput(args.flags, undefined, false);
+            const body = {};
+            if (supplied)
+                body.input = supplied;
+            if (args.flags.headless)
+                body.mode = 'headless';
+            let res = await post(`/credentials/${id}/rotate`, body);
+            if (res.data?.authorizeUrl) {
+                if (args.flags.json)
+                    console.log(JSON.stringify(res.data, null, 2));
+                else
+                    console.log(pendingRedirectMessage(res.data, res.data.connectorKey ?? '<service>'));
+                if (args.flags.open)
+                    await openInBrowser(res.data.authorizeUrl);
+                return;
+            }
+            // A pasted-key service answers a rotate with the form to fill in.
+            // Sending {} and reporting "Rotated." left the old secret in place.
+            if (res.data?.pending && res.data.form) {
+                const form = res.data.form;
+                if (form.keyPageUrl)
+                    console.log(`Create the replacement key at: ${form.keyPageUrl}`);
+                requireTty(`rotate ${id}`);
+                const input = await promptForSchema(form.schema);
+                if (Object.keys(input).length === 0)
+                    throw new Error('nothing entered; the credential was left as it was');
+                res = await post(`/credentials/${id}/rotate`, { input });
+            }
+            out(args, res.data, () => `Rotated.\n${formatConnection(res.data.connection ?? res.data)}`);
+            return;
+        }
+        case 'delete': {
+            const id = needArg(args.positional, 0, 'credential id', 'delete <id>');
+            const res = await q(`/credentials/${id}`, { method: 'DELETE' });
+            out(args, res?.data ?? { id, deleted: true }, () => 'Deleted.');
+            return;
+        }
+        case 'grants': {
+            const id = needArg(args.positional, 0, 'credential id', 'grants <id>');
+            const res = await q(`/credentials/${id}/grants`);
+            out(args, res.data, () => (res.data.length ? res.data.map(formatGrant).join('\n') : 'No grants: only the owner (and org admins for org credentials) can use it.'));
+            return;
+        }
+        case 'grant': {
+            const id = needArg(args.positional, 0, 'credential id', 'grant <id> --principal p --to id');
+            const res = await post(`/credentials/${id}/grants`, grantBody(args.flags));
+            out(args, res.data, () => `Granted.\n${formatGrant(res.data)}`);
+            return;
+        }
+        case 'revoke': {
+            const id = needArg(args.positional, 0, 'credential id', 'revoke <id> <grantId>');
+            const grantId = needArg(args.positional, 1, 'grant id', 'revoke <id> <grantId>');
+            const res = await q(`/credentials/${id}/grants/${grantId}`, { method: 'DELETE' });
+            out(args, res?.data ?? { id: grantId, revoked: true }, () => 'Revoked.');
+            return;
+        }
+        default:
+            console.error(`Unknown command: ${args.command}\n`);
+            printHelp();
+            process.exit(EXIT.USAGE);
+    }
+}
+const invokedDirectly = process.argv[1] && /credentials-cli|almyty-credentials|dist\/index\.js|src\/index\.ts/.test(process.argv[1]) && !process.env.VITEST;
+if (invokedDirectly) {
+    main().catch((err) => {
+        console.error(describeError(err, process.env.ALMYTY_URL));
+        process.exit(exitCodeFor(err));
+    });
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare function readVersion(fallback?: string): string;
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,22 @@
+/**
+ * The CLI's own version, read from its package.json at startup.
+ *
+ * It used to be a hardcoded string, which drifted: `--version` answered
+ * 0.1.0 while the published package was 1.2.0, so a bug report never
+ * identified the build it came from. Both `dist/index.js` and `src/index.ts`
+ * sit one directory below the package root, so the same relative path
+ * resolves for the built bin and for `tsx src/index.ts`.
+ */
+import { readFileSync } from 'node:fs';
+export function readVersion(fallback = '0.0.0') {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
+        return typeof pkg.version === 'string' && pkg.version.length > 0
+            ? pkg.version
+            : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+export const VERSION = readVersion();

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@almyty/credentials",
+  "version": "1.5.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Keys, tokens and accounts for almyty from your terminal: list services, add by key or sign-in, check, replace, delete, share.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "almyty-credentials": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "almyty",
+    "credentials",
+    "cli"
+  ],
+  "author": "almyty",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@almyty/client": "^1.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.4.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.1.0"
+  },
+  "homepage": "https://almyty.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/almyty-inc/almyty.git",
+    "directory": "packages/credentials-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/almyty-inc/almyty/issues"
+  }
+}