@cello-protocol/cli 0.0.234 → 0.0.236

package/dist/arg-parse.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared argv parsing primitives.
+ *
+ * It lives here, not in cli-args.ts, so that BOTH the registry (which parses a command's args
+ * inside its run()) and cli-args (which validates them before dispatch) can use it without an
+ * import cycle: cli-args → registry → arg-parse, never back.
+ */
+/**
+ * Split a subcommand's argv into the `--agent <name>` flag and the remaining positionals.
+ *
+ * The flag's value is excluded ONLY when the flag exists. An unguarded `i === agentIdx + 1` filter
+ * is wrong: with --agent ABSENT, agentIdx is -1 and the predicate silently drops positional index 0
+ * — `cello moniker set Bob` / `cello contact list` would print usage instead of dispatching.
+ */
+export declare function splitAgentFlag(args: string[]): {
+    agent: string | undefined;
+    positional: string[];
+};
+//# sourceMappingURL=arg-parse.d.ts.map

package/dist/arg-parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arg-parse.d.ts","sourceRoot":"","sources":["../src/arg-parse.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAalG"}

package/dist/arg-parse.js

@@ -0,0 +1,29 @@
+/**
+ * Shared argv parsing primitives.
+ *
+ * It lives here, not in cli-args.ts, so that BOTH the registry (which parses a command's args
+ * inside its run()) and cli-args (which validates them before dispatch) can use it without an
+ * import cycle: cli-args → registry → arg-parse, never back.
+ */
+/**
+ * Split a subcommand's argv into the `--agent <name>` flag and the remaining positionals.
+ *
+ * The flag's value is excluded ONLY when the flag exists. An unguarded `i === agentIdx + 1` filter
+ * is wrong: with --agent ABSENT, agentIdx is -1 and the predicate silently drops positional index 0
+ * — `cello moniker set Bob` / `cello contact list` would print usage instead of dispatching.
+ */
+export function splitAgentFlag(args) {
+    // POSIX `--` end-of-flags terminator: everything after the first `--` is a positional VALUE,
+    // verbatim — so a value that starts with `-` (a negative number, or an away text like
+    // "- back Monday") can be passed. --agent is recognized only BEFORE the terminator.
+    const ddIdx = args.indexOf("--");
+    const flagScan = ddIdx === -1 ? args : args.slice(0, ddIdx);
+    const afterTerminator = ddIdx === -1 ? [] : args.slice(ddIdx + 1);
+    const agentIdx = flagScan.indexOf("--agent");
+    const agent = agentIdx !== -1 ? flagScan[agentIdx + 1] : undefined;
+    const positional = flagScan
+        .filter((a, i) => !(a === "--agent" || (agentIdx !== -1 && i === agentIdx + 1)))
+        .concat(afterTerminator);
+    return { agent, positional };
+}
+//# sourceMappingURL=arg-parse.js.map

package/dist/arg-parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arg-parse.js","sourceRoot":"","sources":["../src/arg-parse.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,IAAc;IAC3C,6FAA6F;IAC7F,sFAAsF;IACtF,oFAAoF;IACpF,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,QAAQ,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAC5D,MAAM,eAAe,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IAClE,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACnE,MAAM,UAAU,GAAG,QAAQ;SACxB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,CAAC,QAAQ,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC;SAC/E,MAAM,CAAC,eAAe,CAAC,CAAC;IAC3B,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AAC/B,CAAC"}

package/dist/bin/cello.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * cello — the CELLO CLI binary.
+ *
+ * There is no dispatch switch here. Every command lives in the registry (src/registry.ts), which is
+ * also what renders `cello --help` and per-command help — so dispatch, the command table, and the
+ * help text cannot drift apart. Adding a command means adding one registry entry; this binary does
+ * not change.
+ *
+ * The bash-adapter contract (§3): a command's JSON result goes to stdout, a structured failure goes
+ * to stderr VERBATIM, and the exit code branches on it — so any bash-capable agent can drive a
+ * CELLO node with `cello <cmd> | jq` and `$?`, with no MCP dependency.
+ */
+export {};
+//# sourceMappingURL=cello.d.ts.map

package/dist/bin/cello.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cello.d.ts","sourceRoot":"","sources":["../../src/bin/cello.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;GAWG"}

package/dist/bin/cello.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cello.js","sourceRoot":"","sources":["../../src/bin/cello.ts"],"names":[],"mappings":"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"}

package/dist/cli-args.d.ts

@@ -0,0 +1,62 @@
+/**
+ * CLI argument handling — validation that runs BEFORE dispatch, kept out of src/bin/cello.ts so the
+ * usage surface is testable without spawning the binary.
+ *
+ * The rules it enforces: USAGE lists EVERY dispatchable command; every subcommand answers
+ * --help/-h; an unrecognized flag is REJECTED rather than coerced into a positional (otherwise
+ * `cello register --help` tries to register an agent literally named "--help").
+ *
+ * This module does not OWN the command list, the help text, or the flag table — it DERIVES all
+ * three from the registry (registry.ts), the single source of truth. That is what makes drift
+ * between dispatch, `cello --help`, and `cello <cmd> --help` structurally impossible rather than
+ * merely discouraged.
+ */
+import { COMMANDS } from "./registry.js";
+export { splitAgentFlag } from "./arg-parse.js";
+/** Every dispatchable command — derived, so it cannot fall out of step with the registry. */
+export declare const KNOWN_COMMANDS: ReadonlySet<string>;
+export type KnownCommand = string;
+/**
+ * The flags that come BEFORE any command — `cello --version`, `cello --help`.
+ *
+ * They were treated as unknown COMMANDS, so `cello --version` printed the entire help text and
+ * exited 1. That is the first thing anyone runs to check an install, and it answered by looking
+ * broken while being fine. `--help` had the same shape: correct output, exit 1, which is what a
+ * script checks. The comment in `USAGE` above has always called it "the top-level `cello --help`" —
+ * the text existed for a flag the dispatcher never actually recognised.
+ *
+ * Kept as a pure function here rather than an `if` in the bin, so it is testable without spawning
+ * the binary — the reason every other argument rule lives in this module.
+ */
+export declare function topLevelFlag(command: string | undefined): "version" | "help" | undefined;
+/**
+ * The top-level `cello --help`.
+ *
+ * Opens with what CELLO is + the onboarding path a first-time user needs. The command list is a
+ * DESCRIBED table rendered from each registry entry's `summary`. Arguments stay in per-command
+ * `--help`.
+ */
+export declare const USAGE: string;
+/** Per-command help — the registry entry's own text, verbatim. */
+export declare function helpForCommand(command: string, args?: readonly string[]): string;
+export type ArgsCheck = {
+    kind: "ok";
+} | {
+    kind: "help";
+} | {
+    kind: "unknown_flag";
+    flag: string;
+};
+/**
+ * Validate a subcommand's arguments BEFORE dispatch.
+ *  - --help / -h ANYWHERE → help. This is a dedicated pre-scan so help wins even when it
+ *    follows an unknown flag or sits where a value-consuming flag would swallow it — asking for
+ *    help must never be masked by another argument error.
+ *  - any other dash-prefixed token the command does not recognize → unknown_flag
+ *    (never silently coerced into a positional).
+ *  - after a POSIX `--` terminator, everything is a positional VALUE, verbatim.
+ */
+export declare function checkArgs(command: string, args: string[]): ArgsCheck;
+/** The registry, re-exported for callers that want to enumerate commands (e.g. the dispatcher). */
+export { COMMANDS };
+//# sourceMappingURL=cli-args.d.ts.map

package/dist/cli-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAA4D,MAAM,eAAe,CAAC;AAInG,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD,6FAA6F;AAC7F,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAA2B,CAAC;AAE3E,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAIxF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,QAwBiF,CAAC;AAEpG,kEAAkE;AAClE,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,SAAS,MAAM,EAAO,GAAG,MAAM,CAUpF;AAED,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GACd;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3C;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,CAoBpE;AAED,mGAAmG;AACnG,OAAO,EAAE,QAAQ,EAAE,CAAC"}

package/dist/cli-args.js

@@ -0,0 +1,119 @@
+/**
+ * CLI argument handling — validation that runs BEFORE dispatch, kept out of src/bin/cello.ts so the
+ * usage surface is testable without spawning the binary.
+ *
+ * The rules it enforces: USAGE lists EVERY dispatchable command; every subcommand answers
+ * --help/-h; an unrecognized flag is REJECTED rather than coerced into a positional (otherwise
+ * `cello register --help` tries to register an agent literally named "--help").
+ *
+ * This module does not OWN the command list, the help text, or the flag table — it DERIVES all
+ * three from the registry (registry.ts), the single source of truth. That is what makes drift
+ * between dispatch, `cello --help`, and `cello <cmd> --help` structurally impossible rather than
+ * merely discouraged.
+ */
+import { COMMANDS, commandNames, findCommand, flagsFor, renderCommandsTable } from "./registry.js";
+// Re-exported for the dispatch layer and existing callers (its home is arg-parse.ts, which both
+// this module and the registry depend on — see the import-cycle note there).
+export { splitAgentFlag } from "./arg-parse.js";
+/** Every dispatchable command — derived, so it cannot fall out of step with the registry. */
+export const KNOWN_COMMANDS = new Set(commandNames());
+/**
+ * The flags that come BEFORE any command — `cello --version`, `cello --help`.
+ *
+ * They were treated as unknown COMMANDS, so `cello --version` printed the entire help text and
+ * exited 1. That is the first thing anyone runs to check an install, and it answered by looking
+ * broken while being fine. `--help` had the same shape: correct output, exit 1, which is what a
+ * script checks. The comment in `USAGE` above has always called it "the top-level `cello --help`" —
+ * the text existed for a flag the dispatcher never actually recognised.
+ *
+ * Kept as a pure function here rather than an `if` in the bin, so it is testable without spawning
+ * the binary — the reason every other argument rule lives in this module.
+ */
+export function topLevelFlag(command) {
+    if (command === "--version" || command === "-v")
+        return "version";
+    if (command === "--help" || command === "-h")
+        return "help";
+    return undefined;
+}
+/**
+ * The top-level `cello --help`.
+ *
+ * Opens with what CELLO is + the onboarding path a first-time user needs. The command list is a
+ * DESCRIBED table rendered from each registry entry's `summary`. Arguments stay in per-command
+ * `--help`.
+ */
+export const USAGE = "CELLO — a peer-to-peer identity & trust layer for agent-to-agent communication.\n" +
+    "\n" +
+    "First-time setup:  cello login  →  cello create-agent <name>  →  cello register-agent <name> <token>  →  cello status\n" +
+    "  (get <token> from the CELLO Operations Agent on Telegram; 'cello login' starts the local daemon.)\n" +
+    "\n" +
+    "Usage: cello <command> [args]\n" +
+    "\n" +
+    renderCommandsTable() +
+    "\n" +
+    "\n" +
+    "Run 'cello <command> --help' for details on any command.\n" +
+    // Scoped deliberately: only the parity commands (jsonOut) honor the full §3 contract — JSON on
+    // stdout, structured error on stderr. Some older commands (login, logout, backup, …) still print
+    // human text. Claiming the contract for EVERY command would be a promise the binary does not
+    // keep, made to precisely the reader who would script against it.
+    //
+    // DOD-M15-CLIJSON-1: this sentence USED to name `register-agent` among the human-text commands,
+    // and that is no longer true — it prints JSON on stdout and its guidance on stderr, on BOTH the
+    // success and failure paths. Leaving the old wording would have told the one reader it is
+    // addressed to — someone deciding whether to script onboarding — not to, about the command that
+    // now supports it.
+    "The session and agent commands (agents, use-agent, initiate-session, send, receive, close-session,\n" +
+    "…) print JSON and exit non-zero on failure, so any bash-capable agent can drive CELLO with no MCP\n" +
+    "dependency. Where a command has an MCP tool, it carries the SAME name: cello send ↔ cello_send.";
+/** Per-command help — the registry entry's own text, verbatim. */
+export function helpForCommand(command, args = []) {
+    // SUB-VERB HELP WINS. `-h` is answered here, before dispatch, so a per-verb help block inside
+    // a command's own handler could never run — `cello doc propose -h` printed the whole doc list,
+    // which names propose's six flags and explains none of them.
+    const sub = args.find((a) => !a.startsWith("-"));
+    if (sub) {
+        const detail = findCommand(command)?.subHelp?.[sub];
+        if (detail)
+            return detail;
+    }
+    return findCommand(command)?.help ?? USAGE;
+}
+/**
+ * Validate a subcommand's arguments BEFORE dispatch.
+ *  - --help / -h ANYWHERE → help. This is a dedicated pre-scan so help wins even when it
+ *    follows an unknown flag or sits where a value-consuming flag would swallow it — asking for
+ *    help must never be masked by another argument error.
+ *  - any other dash-prefixed token the command does not recognize → unknown_flag
+ *    (never silently coerced into a positional).
+ *  - after a POSIX `--` terminator, everything is a positional VALUE, verbatim.
+ */
+export function checkArgs(command, args) {
+    // The help check MUST respect the `--` terminator too. It used to scan the whole argv, so
+    // `cello attestations issue <pubkey> -- she walked me through the -h flag` printed help instead
+    // of issuing the signal — the terminator was honoured for unknown flags and ignored for help,
+    // which is the surprising half. Commands that take free prose (issue, consent refuse, contact
+    // set-away) are exactly the ones where a bare `-h` appears as ordinary text.
+    const terminator = args.indexOf("--");
+    const flagArgs = terminator === -1 ? args : args.slice(0, terminator);
+    if (flagArgs.some((a) => a === "--help" || a === "-h"))
+        return { kind: "help" };
+    const known = flagsFor(command);
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--")
+            break; // POSIX end-of-flags — everything after is a positional value
+        if (arg.startsWith("-")) {
+            const spec = known.get(arg);
+            if (!spec)
+                return { kind: "unknown_flag", flag: arg };
+            if (spec.consumesValue)
+                i++; // its value is not itself a flag
+        }
+    }
+    return { kind: "ok" };
+}
+/** The registry, re-exported for callers that want to enumerate commands (e.g. the dispatcher). */
+export { COMMANDS };
+//# sourceMappingURL=cli-args.js.map

package/dist/cli-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"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"}

package/dist/commands.d.ts

@@ -0,0 +1,139 @@
+/**
+ * CLI command implementations for the `cello` binary.
+ */
+import { type IpcClient, type Logger } from "@cello-protocol/daemon";
+/**
+ * M8C-LOGINSTART-1 CORE: bring every loaded agent online. Called by `cello login` after the daemon
+ * is up. login ALWAYS completes — a per-agent start failure is COLLECTED, never thrown, so one bad
+ * agent can't abort login. `cello_start_agent` is idempotent, so re-login is safe. The per-agent
+ * `autoStart: false` opt-out is PARKED until the M9 config store lands (D14).
+ * Lives here rather than inline in login() so it is unit-testable against an in-process daemon.
+ */
+export declare function autoStartAllAgents(client: IpcClient): Promise<{
+    started: string[];
+    failed: Array<{
+        name: string;
+        reason: string;
+    }>;
+}>;
+export interface CommandResult {
+    exitCode: number;
+    /**
+     * STDOUT. For a command whose help promises JSON, this must be JSON and NOTHING ELSE — see
+     * `guidance` below for why that had to be written down.
+     */
+    output: string;
+    /**
+     * STDERR — guidance for a human, kept OUT of the data stream.
+     *
+     * DOD-M15-CLIJSON-1: `register-agent` used to append its "Next: run cello status…" hint to
+     * `output`, after the JSON. It exits 0, the registration succeeds, and every consumer that parses
+     * the output dies on the trailing prose — with a parse error naming a byte offset, so it reads as
+     * "registration is broken" when registration is fine. Five end-to-end journeys died at their first
+     * line on it.
+     *
+     * The hint is worth keeping: it is what tells a new operator that registration is asynchronous and
+     * may take a minute. It just belongs on stderr, which is what stderr is for. A human sees both
+     * streams in a terminal and loses nothing; a script sees clean JSON.
+     */
+    guidance?: string;
+}
+export declare function login(celloDir: string, daemonBin: string, logger: Logger): Promise<CommandResult>;
+/**
+ * One line when the classifier is not installed-and-verified, empty when it is.
+ *
+ * Never throws and never blocks login: a screener check that could break sign-in would be a worse
+ * defect than the one it reports.
+ */
+export declare function screenerLoginLine(stateImpl?: () => Promise<{
+    state: string;
+    problem?: string;
+}>): Promise<string>;
+/**
+ * M8C-LOGINSTART-1: compose the operator-facing auto-start summary — every failed agent enumerated
+ * by name + reason. Pure + exported so the enumeration string is directly testable.
+ */
+export declare function formatLoginSummary(result: {
+    started: string[];
+    failed: Array<{
+        name: string;
+        reason: string;
+    }>;
+}): string;
+export declare function logout(celloDir: string, onProgress?: (line: string) => void, waitOpts?: {
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<CommandResult>;
+export declare function register(celloDir: string, agent: string, preAuthToken: string, phoneStub?: string): Promise<CommandResult>;
+/**
+ * createAgent(celloDir, name):
+ *  - Connect to the daemon, send 'cello_create_agent' with { name }.
+ *  - The daemon generates a fresh K_local seed, writes it as an `agents` row in the encrypted DB
+ *    (PERSIST-002 — no key file), and wires the agent in so it can be registered immediately.
+ */
+export declare function createAgent(celloDir: string, name: string): Promise<CommandResult>;
+/**
+ * refreshShares(celloDir, name): M8B DOD-REFRESH-1.
+ *  - Connect to the daemon, send 'cello_refresh_shares' with { agent }.
+ *  - The daemon runs a proactive share refresh across the consortium: every shareholder rotates its
+ *    share to a new epoch, the group public key is unchanged, and old-epoch shares no longer sign.
+ */
+export declare function refreshShares(celloDir: string, name: string): Promise<CommandResult>;
+/**
+ * relayReceipts(celloDir, name): M8B DOD-RELAYSIG-1.
+ *  - Connect to the daemon, send 'cello_get_relay_receipts' with { agent }.
+ *  - Returns the agent's durably-stored, signature-verified relay ordering-record receipts.
+ */
+export declare function relayReceipts(celloDir: string, name: string): Promise<CommandResult>;
+/**
+ * removeAgent(celloDir, name) — CELLO-M7-REMOVE-001 (DOD-REMOVE-1):
+ *  - Connect to the daemon, send 'cello_remove_agent' with { name }.
+ *  - The daemon RETIRES the agent (state=retired; row, keys, and history KEPT for accountability) and
+ *    FREES the human name for reuse. One-way.
+ */
+export declare function removeAgent(celloDir: string, name: string): Promise<CommandResult>;
+export declare function status(celloDir: string): Promise<CommandResult>;
+export type SessionFilter = "open" | "closed" | "failed" | "all";
+/**
+ * `cello sessions [--open|--closed|--failed|--all] [--limit N]` — the full, queryable session
+ * history (the discovery surface `cello status` deliberately does NOT dump). Defaults to OPEN
+ * (live + resumable) so a long-lived agent's failed/closed history doesn't flood it, and caps the
+ * count at the daemon's default limit. Output reports `totalMatched` so the operator can tell when
+ * results were truncated.
+ */
+export declare function sessions(celloDir: string, opts?: {
+    filter?: SessionFilter;
+    limit?: number;
+}): Promise<CommandResult>;
+/** M8C-TGDOOR-1: `cello telegram set-token <bot_token> <allowlisted_chat_id>` — persists the
+ *  daemon-wide bot credentials (narrow, dedicated surface; NOT folded into the parked `cello
+ *  config`, since a bot token has no sensible default and can't wait for M9-CFG-001). */
+/**
+ * `cello attestations` — YOUR words about ANOTHER agent, and what became of them.
+ *
+ * SEPARATE FROM `trust-signals` ON PURPOSE. On the wire an attestation IS a trust signal, so folding
+ * the two together is the obvious move — and it is the wrong one. A trust signal is the NETWORK
+ * verifying an attribute of yours; an attestation is a PERSON vouching for a PERSON. That second
+ * thing is the primitive collaboration rests on, and filing it as a subcommand of a wallet listing
+ * makes the most important capability the hardest one to find.
+ *
+ * Subcommands:
+ *   issue <pubkey> <text…>  — attest to something you have seen them do
+ *   issued                  — what happened to the ones you wrote
+ *
+ * The receiving direction — what others wrote about YOU — is `cello attestation-consent`.
+ */
+export declare function attestations(celloDir: string, sub: string, args: string[]): Promise<CommandResult>;
+/**
+ * `cello trust-signals` — inspect and manage the operator's trust-signal wallet.
+ *
+ * Subcommands:
+ *   list                   — tabular view of all signals (includes default column)
+ *   view <hash-prefix>     — full decoded payload for one signal
+ *   enable <hash-prefix>   — include signal in the default presentation bundle
+ *   disable <hash-prefix>  — exclude signal from the default bundle
+ *   revoke <hash-prefix>   — tombstone at the directory AND hard-delete locally
+ */
+export declare function trustSignals(celloDir: string, sub: string, args: string[]): Promise<CommandResult>;
+export declare function telegramSetToken(celloDir: string, botToken: string, chatId: string): Promise<CommandResult>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"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"}