@ujexdev/cli 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Akshay Sarode
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,31 @@
+# @ujexdev/cli
+
+Command-line client for Ujex Postbox, approvals, Recall/Memory, Gateway,
+tools, and audit exports.
+
+## Install
+
+```bash
+npm install -g @ujexdev/cli
+```
+
+## Configure
+
+Create an agent in https://app.ujex.dev/settings, then save the one-time device
+key locally:
+
+```bash
+ujex init <agentId> <deviceKey>
+```
+
+## Use
+
+```bash
+ujex whoami
+ujex send alice@example.com "hello" "Sent from an agent"
+ujex ask "Approve this action?"
+ujex memory search "invoice preference"
+ujex audit verify ./evidence-bundle
+```
+
+Run `ujex --help` for the full command list.

package/dist/beads.js

@@ -0,0 +1,66 @@
+/**
+ * Beads-shaped JSONL export/import for Recall (plan-v4 Phase 9).
+ *
+ * Steve Yegge's Beads pattern: agent state as JSONL-in-git, hash IDs,
+ * mergeable across agents and sessions. Ujex Recall (Markdown +
+ * frontmatter) is already on this side of the trend; this module
+ * round-trips Recall ↔ Beads-shaped JSONL so users can keep their
+ * Ujex memory in git, diff it in PRs, and merge across branches.
+ *
+ * JSONL row shape (one per memory file):
+ *   {
+ *     id: "blake3:<hash>",      // content-addressed id
+ *     name: "research-notes.md",
+ *     frontmatter: {type, tags, pinned, description, version},
+ *     body: "<markdown body>",
+ *     created_at: "ISO-8601",
+ *     updated_at: "ISO-8601"
+ *   }
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+function contentHash(name, body) {
+    // Substitute sha256 for blake3 — blake3 needs a native binding; sha256
+    // ships with node:crypto and is stable enough for content-addressing.
+    return 'sha256:' + createHash('sha256').update(name).update('\n').update(body).digest('hex').slice(0, 24);
+}
+export function exportToBeadsJsonl(memories, outPath) {
+    const rows = memories.map((m) => {
+        // Split frontmatter (---\n...\n---\nbody).
+        let fm = {};
+        let body = m.content;
+        if (m.content.startsWith('---\n')) {
+            const end = m.content.indexOf('\n---\n', 4);
+            if (end > 0) {
+                const fmRaw = m.content.slice(4, end);
+                body = m.content.slice(end + 5);
+                for (const line of fmRaw.split('\n')) {
+                    const idx = line.indexOf(':');
+                    if (idx > 0)
+                        fm[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+                }
+            }
+        }
+        return {
+            id: contentHash(m.name, body),
+            name: m.name,
+            frontmatter: { ...fm, ...(m.metadata ?? {}) },
+            body,
+            created_at: m.createdAt ?? new Date().toISOString(),
+            updated_at: m.updatedAt ?? new Date().toISOString(),
+        };
+    });
+    writeFileSync(outPath, rows.map((r) => JSON.stringify(r)).join('\n') + '\n', 'utf8');
+    return { count: rows.length };
+}
+export function importFromBeadsJsonl(inPath) {
+    const raw = readFileSync(inPath, 'utf8');
+    return raw.split('\n').filter(Boolean).map((line) => JSON.parse(line));
+}
+export function rowToUjexMemoryWrite(row) {
+    const fmLines = Object.entries(row.frontmatter ?? {})
+        .map(([k, v]) => `${k}: ${typeof v === 'string' ? v : JSON.stringify(v)}`)
+        .join('\n');
+    const content = `---\n${fmLines}\n---\n${row.body}`;
+    return { name: row.name, content };
+}

package/dist/imports.js

@@ -0,0 +1,84 @@
+/**
+ * Migration importers for the `ujex import` subcommand.
+ *
+ * Supports:
+ *   ujex import mem0     <export.json>   — Mem0 user-memory dump
+ *   ujex import zep      <export.json>   — Zep user-graph dump
+ *   ujex import letta    <export.json>   — Letta agent state dump
+ *
+ * Each importer normalizes the source schema, writes Ujex-shaped rows,
+ * and audits each migrated row.
+ */
+import { readFileSync } from 'node:fs';
+export async function importFile(source, path, call) {
+    const raw = readFileSync(path, 'utf8');
+    switch (source) {
+        case 'mem0': return importMem0(raw, call);
+        case 'zep': return importZep(raw, call);
+        case 'letta': return importLetta(raw, call);
+        default:
+            throw new Error(`unknown source: ${source}`);
+    }
+}
+async function importMem0(raw, call) {
+    const data = JSON.parse(raw);
+    const memories = data.memories ?? [];
+    const warnings = [];
+    let written = 0;
+    for (const m of memories) {
+        const name = `mem0-${m.id}.md`;
+        const fm = ['---', 'source: mem0', `mem0_id: ${m.id}`, `created_at: ${m.created_at ?? ''}`, '---', ''].join('\n');
+        const content = fm + m.memory;
+        try {
+            await call('memoryWrite', { name, content, tags: ['mem0-import'] });
+            written++;
+        }
+        catch (e) {
+            warnings.push(`failed ${m.id}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    return { source: 'mem0', itemsRead: memories.length, itemsWritten: written, warnings };
+}
+async function importZep(raw, call) {
+    const data = JSON.parse(raw);
+    const facts = data.facts ?? [];
+    const warnings = [];
+    let written = 0;
+    for (const f of facts) {
+        const name = `zep-${f.uuid}.md`;
+        const fm = ['---', 'source: zep', `zep_uuid: ${f.uuid}`, `valid_at: ${f.validAt ?? ''}`, '---', ''].join('\n');
+        try {
+            await call('memoryWrite', { name, content: fm + f.fact, tags: ['zep-import'] });
+            written++;
+        }
+        catch (e) {
+            warnings.push(`failed ${f.uuid}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    return { source: 'zep', itemsRead: facts.length, itemsWritten: written, warnings };
+}
+async function importLetta(raw, call) {
+    const data = JSON.parse(raw);
+    const warnings = [];
+    let written = 0;
+    const all = [
+        ...(data.archival ?? []).map((m) => ({ kind: 'archival', ...m })),
+        ...(data.recall ?? []).map((m) => ({ kind: 'recall', ...m })),
+    ];
+    if (data.core?.persona)
+        all.push({ kind: 'core_persona', id: 'persona', text: data.core.persona });
+    if (data.core?.human)
+        all.push({ kind: 'core_human', id: 'human', text: data.core.human });
+    for (const m of all) {
+        const name = `letta-${m.kind}-${m.id}.md`;
+        const fm = ['---', 'source: letta', `letta_kind: ${m.kind}`, `letta_id: ${m.id}`, '---', ''].join('\n');
+        try {
+            await call('memoryWrite', { name, content: fm + m.text, tags: ['letta-import', `letta-${m.kind}`] });
+            written++;
+        }
+        catch (e) {
+            warnings.push(`failed ${m.id}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    return { source: 'letta', itemsRead: all.length, itemsWritten: written, warnings };
+}

package/dist/index.js

@@ -0,0 +1,575 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createHash, createPublicKey, verify as verifySignature } from 'node:crypto';
+import { UjexClient } from '@ujexdev/client';
+import { verifyRecords } from '@ujexdev/audit-chain';
+import { importFile } from './imports.js';
+import { exportToBeadsJsonl, importFromBeadsJsonl, rowToUjexMemoryWrite } from './beads.js';
+const CFG_DIR = join(homedir(), '.config', 'ujex');
+const CFG_PATH = join(CFG_DIR, 'config.json');
+const FIREBASE = {
+    apiKey: 'AIzaSyCWJzLBaXapTm9TAqQMmtNWT4GxcPO5H9M',
+    authDomain: 'axy-ujex.firebaseapp.com',
+    projectId: 'axy-ujex',
+    appId: '1:692303724344:web:879a1fb4f4244e783a4bcd',
+};
+function loadConfig() {
+    if (!existsSync(CFG_PATH)) {
+        console.error(`no config at ${CFG_PATH}. run: ujex init <agentId> <deviceKey>`);
+        process.exit(2);
+    }
+    return JSON.parse(readFileSync(CFG_PATH, 'utf8'));
+}
+function saveConfig(cfg) {
+    mkdirSync(CFG_DIR, { recursive: true, mode: 0o700 });
+    writeFileSync(CFG_PATH, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+}
+async function client() {
+    const c = loadConfig();
+    const ap = new UjexClient({ firebase: FIREBASE, agentId: c.agentId, deviceKey: c.deviceKey });
+    await ap.connect();
+    return ap;
+}
+const HELP = `ujex <command>
+
+  init <agentId> <deviceKey>              save credentials to ~/.config/ujex/config.json
+  whoami                                  print agentId and scopes
+  send <to> <subject> <body> [--require-human] [--approval-ttl=N]
+                                          send a Postbox email
+  ask <prompt>                            ask the human for approval
+  search <query>                          search Recall/Memory
+  memory list
+  memory read <name>
+  memory write <name> <content>
+  memory append <name> <content>
+  memory search <query>
+  memory index
+
+  scheduler create <name> <cron> <webhookUrl> [--payload=<json>] [--max-attempts=N]
+  scheduler replay <agentId> <jobName> <runId>
+
+  tools register <agentId> <name> <kind> <url> [--auth-token=<t>] [--connection-id=<id>]
+  tools list
+  tools invoke <name> [--args=<json>] [--timeout-ms=N]
+  tools cred <name>                       escape hatch — decrypt auth token
+  tools connection-register <agentId> <provider> [--scopes=a,b] [--access-token=<t>] [--refresh-token=<t>]
+  tools connections [agentId]
+  tools revoke-connection <agentId> <connectionId>
+
+  gateway claim <fqdn> [--mode=duckdns|custom]
+  gateway updateIp <fqdn> <ip>            (alias: updateIp)
+  gateway issue <fqdn> [--staging]        duckdns cert (alias: issue)
+  gateway acme-start <fqdn> [--staging]   custom-domain ACME step 1
+  gateway acme-finish <orderId>           custom-domain ACME step 2
+  gateway duckdns-token <token>           human-only: stash DuckDNS token (KMS)
+  gateway get-cert <fqdn> [--id=<id>]     return PEMs
+
+  secret set <name> <value>               store KMS-encrypted secret
+  secret get <name>                       retrieve secret
+
+  audit verify <dir|records.jsonl>        verify an AAT bundle offline (no path: check live chain)
+  audit export-aat --from=ISO --to=ISO [--out=DIR] [--sign-manifest]
+                                          export an IETF AAT bundle (records, manifest, optional signature)
+  audit export-iso42005 --from=ISO --to=ISO
+                                          ISO/IEC 42005 evidence pack
+  audit list [--limit=N] [--before=SEQ]   list my audit entries
+
+  identity passport <agentId>             print signed agent passport
+
+  import mem0|zep|letta <file.json>
+                                          migrate from a competitor product
+  memory export-beads <out.jsonl>         export memory to git-mergeable JSONL (Yegge Beads pattern)
+  memory import-beads <in.jsonl>          re-import a Beads JSONL bundle
+`;
+function flagValue(args, prefix) {
+    const found = args.find((a) => a.startsWith(prefix));
+    return found?.slice(prefix.length);
+}
+function hasFlag(args, flag) {
+    return args.includes(flag);
+}
+function withoutFlags(args) {
+    return args.filter((a) => !a.startsWith('--'));
+}
+function parseJSONFlag(args, prefix) {
+    const raw = flagValue(args, prefix);
+    if (raw === undefined)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+function parseJsonl(text) {
+    return text
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .map((l) => JSON.parse(l));
+}
+function bundleSha256(text) {
+    const body = text.endsWith('\n') ? text.slice(0, -1) : text;
+    return createHash('sha256').update(body, 'utf8').digest('hex');
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const obj = value;
+    return `{${Object.keys(obj).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(',')}}`;
+}
+function verifyManifestSignature(manifest, sig) {
+    const signature = typeof sig.signature === 'string' ? sig.signature : '';
+    const publicKeyPem = typeof sig.publicKeyPem === 'string' ? sig.publicKeyPem : '';
+    if (manifest.public_key_id && sig.publicKeyId !== manifest.public_key_id)
+        return 'manifest signature key id mismatch';
+    if (!signature || !publicKeyPem)
+        return 'manifest.sig missing signature/publicKeyPem';
+    const ok = verifySignature(null, Buffer.from(canonicalJson(manifest)), createPublicKey(publicKeyPem), Buffer.from(signature, 'base64'));
+    return ok ? null : 'manifest signature mismatch';
+}
+/**
+ * Offline AAT-bundle verification — no config, no network, no firebase.
+ * Accepts a bundle directory (records.jsonl + optional manifest.json) or a raw
+ * records.jsonl. Returns the process exit code. (.zip is handled by the
+ * stdlib-only Python verifier, which this points to.)
+ */
+async function offlineAuditVerify(path) {
+    if (path.endsWith('.zip')) {
+        console.error('The JS CLI does not read .zip bundles. Extract it, or use the stdlib Python verifier:');
+        console.error(`  pip install ujex-audit-chain && python -m ujex_audit_chain verify ${path}`);
+        return 2;
+    }
+    let recordsText;
+    let manifest = null;
+    let manifestSig = null;
+    try {
+        if (existsSync(path) && statSync(path).isDirectory()) {
+            recordsText = readFileSync(join(path, 'records.jsonl'), 'utf8');
+            const mp = join(path, 'manifest.json');
+            if (existsSync(mp))
+                manifest = JSON.parse(readFileSync(mp, 'utf8'));
+            const sp = join(path, 'manifest.sig');
+            if (existsSync(sp))
+                manifestSig = JSON.parse(readFileSync(sp, 'utf8'));
+        }
+        else {
+            recordsText = readFileSync(path, 'utf8');
+        }
+    }
+    catch (e) {
+        console.error(`cannot read ${path}: ${e.message}`);
+        return 2;
+    }
+    const rep = await verifyRecords(parseJsonl(recordsText));
+    const errors = [...rep.errors];
+    let ok = rep.ok;
+    if (manifest) {
+        if (manifest.head_hash && manifest.head_hash !== rep.headHash) {
+            ok = false;
+            errors.push('manifest head_hash mismatch');
+        }
+        if (manifest.bundle_sha256 && manifest.bundle_sha256 !== bundleSha256(recordsText)) {
+            ok = false;
+            errors.push('manifest bundle_sha256 mismatch');
+        }
+        if (typeof manifest.record_count === 'number' && manifest.record_count !== rep.recordCount) {
+            ok = false;
+            errors.push('manifest record_count mismatch');
+        }
+        if (manifestSig) {
+            const sigError = verifyManifestSignature(manifest, manifestSig);
+            if (sigError) {
+                ok = false;
+                errors.push(sigError);
+            }
+        }
+    }
+    console.log(`verify: ${ok ? 'OK' : 'FAILED'}`);
+    console.log(`  format        : ${rep.fmt || 'unknown'}`);
+    console.log(`  records       : ${rep.recordCount}`);
+    console.log(`  head_hash     : ${rep.headHash ? rep.headHash.slice(0, 16) + '…' : '(none)'}`);
+    if (rep.fmt === 'aat-export') {
+        console.log(`  links checked : ${rep.linksVerified}`);
+        console.log(`  seq gaps      : ${rep.gaps} (expected for owner-scoped exports)`);
+    }
+    if (!manifest)
+        console.log('  manifest      : (none — head_hash is unanchored)');
+    else
+        console.log(`  manifest sig  : ${manifestSig ? 'checked' : 'none'}`);
+    for (const e of errors)
+        console.error(`  ERROR         : ${e}`);
+    return ok ? 0 : 1;
+}
+async function main() {
+    const [, , cmd, ...args] = process.argv;
+    if (!cmd || cmd === '-h' || cmd === '--help') {
+        console.log(HELP);
+        return;
+    }
+    if (cmd === 'init') {
+        const [agentId, deviceKey] = args;
+        if (!agentId || !deviceKey) {
+            console.error('usage: ujex init <agentId> <deviceKey>');
+            process.exit(2);
+        }
+        saveConfig({ agentId, deviceKey });
+        console.log(`saved ${CFG_PATH}`);
+        return;
+    }
+    // `audit verify <path>` runs fully offline — no config, no network.
+    if (cmd === 'audit' && withoutFlags(args)[0] === 'verify' && withoutFlags(args).length > 1) {
+        process.exit(await offlineAuditVerify(withoutFlags(args)[1]));
+    }
+    const ap = await client();
+    switch (cmd) {
+        case 'whoami': {
+            const c = loadConfig();
+            console.log(JSON.stringify({ agentId: c.agentId }, null, 2));
+            break;
+        }
+        case 'send': {
+            const [to, subject, ...body] = args;
+            if (!to || !subject)
+                throw new Error('usage: ujex send <to> <subject> <body>');
+            const ttlRaw = flagValue(args, '--approval-ttl=');
+            const approvalTtlSec = ttlRaw ? Number(ttlRaw) : undefined;
+            const r = await ap.postbox.send({
+                to: [to],
+                subject,
+                body: withoutFlags(body).join(' '),
+                requireHuman: hasFlag(args, '--require-human'),
+                approvalTtlSec,
+            });
+            console.log(JSON.stringify(r, null, 2));
+            break;
+        }
+        case 'search': {
+            const q = args.join(' ');
+            const r = await ap.memory.search({ query: q, k: 10, includePinned: true });
+            console.log(JSON.stringify(r, null, 2));
+            break;
+        }
+        case 'ask': {
+            const r = await ap.mobile.ask({ prompt: args.join(' ') });
+            console.log(JSON.stringify(r, null, 2));
+            break;
+        }
+        case 'memory': {
+            const [sub, ...rest] = args;
+            if (sub === 'list') {
+                const r = await ap.memory.list({});
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else if (sub === 'read') {
+                const [name] = rest;
+                if (!name)
+                    throw new Error('usage: ujex memory read <name>');
+                const r = await ap.memory.read({ name });
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else if (sub === 'write' || sub === 'append') {
+                const [name, ...content] = rest;
+                if (!name || content.length === 0)
+                    throw new Error(`usage: ujex memory ${sub} <name> <content>`);
+                const input = { name, content: content.join(' ') };
+                const r = sub === 'write'
+                    ? await ap.memory.write(input)
+                    : await ap.memory.append(input);
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else if (sub === 'search') {
+                const query = rest.join(' ');
+                if (!query)
+                    throw new Error('usage: ujex memory search <query>');
+                const r = await ap.memory.search({ query, k: 10, includePinned: true });
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else if (sub === 'index') {
+                const r = await ap.memory.index({});
+                console.log(r.markdown);
+            }
+            else
+                throw new Error('memory list|read|write|append|search|index');
+            break;
+        }
+        case 'updateIp': {
+            const [fqdn, ip] = args;
+            const r = await ap.gateway.updateIp({ fqdn, ip });
+            console.log(JSON.stringify(r, null, 2));
+            break;
+        }
+        case 'issue': {
+            const [fqdn, ...rest] = args;
+            const staging = rest.includes('--staging');
+            const r = await ap.gateway.issue({ fqdn, staging });
+            console.log(JSON.stringify(r, null, 2));
+            break;
+        }
+        case 'secret': {
+            const [sub, name, value] = args;
+            if (sub === 'set') {
+                const c = loadConfig();
+                await ap.secrets.store({ agentId: c.agentId, name, value });
+                console.log('ok');
+            }
+            else if (sub === 'get') {
+                const r = await ap.secrets.get({ name });
+                console.log(r.value);
+            }
+            else
+                throw new Error('secret set|get');
+            break;
+        }
+        case 'scheduler': {
+            const [sub, ...rest] = args;
+            if (sub === 'create') {
+                const [name, cron, webhookUrl] = rest;
+                if (!name || !cron || !webhookUrl)
+                    throw new Error('usage: ujex scheduler create <name> <cron> <webhookUrl> [--payload=<json>] [--max-attempts=N]');
+                const payload = parseJSONFlag(rest, '--payload=');
+                const maxAttemptsRaw = flagValue(rest, '--max-attempts=');
+                const maxAttempts = maxAttemptsRaw ? Number(maxAttemptsRaw) : undefined;
+                const r = await ap.scheduler.createJob({ name, cron, webhookUrl, payload, maxAttempts });
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else if (sub === 'replay') {
+                const [agentId, jobName, runId] = rest;
+                if (!agentId || !jobName || !runId)
+                    throw new Error('usage: ujex scheduler replay <agentId> <jobName> <runId>');
+                const r = await ap.scheduler.dlqReplay({ agentId, jobName, runId });
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else
+                throw new Error('scheduler create|replay');
+            break;
+        }
+        case 'tools': {
+            const [sub, ...rest] = args;
+            if (sub === 'register') {
+                const [agentId, name, kind, url] = rest;
+                if (!agentId || !name || !kind || !url)
+                    throw new Error('usage: ujex tools register <agentId> <name> <kind> <url> [--auth-token=<t>]');
+                if (kind !== 'mcp' && kind !== 'http')
+                    throw new Error('kind must be mcp or http');
+                const authToken = flagValue(rest, '--auth-token=');
+                const connectionId = flagValue(rest, '--connection-id=');
+                const r = await ap.tools.register({ agentId, name, kind, url, authToken, connectionId });
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else if (sub === 'list') {
+                const r = await ap.tools.list({});
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else if (sub === 'invoke') {
+                const [name] = rest;
+                if (!name)
+                    throw new Error('usage: ujex tools invoke <name> [--args=<json>] [--timeout-ms=N]');
+                const toolArgs = parseJSONFlag(rest, '--args=');
+                const tmRaw = flagValue(rest, '--timeout-ms=');
+                const timeoutMs = tmRaw ? Number(tmRaw) : undefined;
+                const r = await ap.tools.invoke({ name, args: toolArgs, timeoutMs });
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else if (sub === 'cred') {
+                const [name] = rest;
+                if (!name)
+                    throw new Error('usage: ujex tools cred <name>');
+                const r = await ap.tools.getCredential({ name });
+                console.log(r.token ?? '');
+            }
+            else if (sub === 'connection-register') {
+                const [agentId, provider] = rest;
+                if (!agentId || !provider)
+                    throw new Error('usage: ujex tools connection-register <agentId> <provider> [--scopes=a,b] [--access-token=<t>] [--refresh-token=<t>]');
+                const scopes = flagValue(rest, '--scopes=')?.split(',').map((s) => s.trim()).filter(Boolean);
+                const accessToken = flagValue(rest, '--access-token=');
+                const refreshToken = flagValue(rest, '--refresh-token=');
+                const r = await ap.tools.registerConnection({ agentId, provider, scopes, accessToken, refreshToken });
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else if (sub === 'connections') {
+                const [agentId] = rest;
+                const target = agentId ?? loadConfig().agentId;
+                const r = await ap.tools.listConnections({ agentId: target });
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else if (sub === 'revoke-connection') {
+                const [agentId, connectionId] = rest;
+                if (!agentId || !connectionId)
+                    throw new Error('usage: ujex tools revoke-connection <agentId> <connectionId>');
+                const r = await ap.tools.revokeConnection({ agentId, connectionId });
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else
+                throw new Error('tools register|list|invoke|cred|connection-register|connections|revoke-connection');
+            break;
+        }
+        case 'gateway': {
+            const [sub, ...rest] = args;
+            if (sub === 'claim') {
+                const [fqdn] = rest;
+                const modeRaw = flagValue(rest, '--mode=');
+                const mode = modeRaw === 'duckdns' || modeRaw === 'custom' ? modeRaw : undefined;
+                const r = await ap.gateway.claimHostname({ fqdn, mode });
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else if (sub === 'updateIp') {
+                const [fqdn, ip] = rest;
+                const r = await ap.gateway.updateIp({ fqdn, ip });
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else if (sub === 'issue') {
+                const [fqdn] = rest;
+                const staging = rest.includes('--staging');
+                const r = await ap.gateway.issue({ fqdn, staging });
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else if (sub === 'acme-start') {
+                const [fqdn] = rest;
+                const staging = rest.includes('--staging');
+                const r = await ap.gateway.acmeStart({ fqdn, staging });
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else if (sub === 'acme-finish') {
+                const [orderId] = rest;
+                if (!orderId)
+                    throw new Error('usage: ujex gateway acme-finish <orderId>');
+                const r = await ap.gateway.acmeFinish({ orderId });
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else if (sub === 'duckdns-token') {
+                const [token] = rest;
+                if (!token)
+                    throw new Error('usage: ujex gateway duckdns-token <token>');
+                const r = await ap.gateway.setDuckDnsToken({ token });
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else if (sub === 'get-cert') {
+                const [fqdn] = rest;
+                const id = flagValue(rest, '--id=');
+                const r = await ap.gateway.getCert({ fqdn, id });
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else
+                throw new Error('gateway claim|updateIp|issue|acme-start|acme-finish|duckdns-token|get-cert');
+            break;
+        }
+        case 'audit': {
+            const [sub] = args;
+            if (sub === 'verify') {
+                const r = await ap.audit?.verify?.();
+                console.log(JSON.stringify(r ?? { note: 'live-chain verify is an HTTPS callable; for OFFLINE bundle verification run: ujex audit verify <dir|records.jsonl>' }, null, 2));
+            }
+            else if (sub === 'export-aat') {
+                const from = flagValue(args, '--from=');
+                const to = flagValue(args, '--to=');
+                const out = flagValue(args, '--out=');
+                if (!from || !to)
+                    throw new Error('usage: ujex audit export-aat --from=ISO --to=ISO [--out=DIR] [--sign-manifest]');
+                const r = await ap.raw.call('auditExportAATBundle', { from, to, signManifest: hasFlag(args, '--sign-manifest') });
+                if (out && r && typeof r === 'object') {
+                    const data = r;
+                    if (out.endsWith('.json')) {
+                        writeFileSync(out, JSON.stringify(data, null, 2));
+                        console.log(`wrote ${out}`);
+                    }
+                    else {
+                        mkdirSync(out, { recursive: true });
+                        writeFileSync(join(out, 'records.jsonl'), data.records_jsonl ?? '');
+                        writeFileSync(join(out, 'manifest.json'), JSON.stringify(data.manifest, null, 2));
+                        if (data.manifest_sig)
+                            writeFileSync(join(out, 'manifest.sig'), JSON.stringify(data.manifest_sig, null, 2));
+                        writeFileSync(join(out, 'trust-bundle.txt'), data.trust_bundle_txt ?? '');
+                        console.log(`wrote ${out}`);
+                    }
+                }
+                else {
+                    console.log(JSON.stringify(r ?? { note: 'callable auditExportAATBundle; invoke via SDK raw' }, null, 2));
+                }
+            }
+            else if (sub === 'export-iso42005') {
+                const from = flagValue(args, '--from=');
+                const to = flagValue(args, '--to=');
+                if (!from || !to)
+                    throw new Error('usage: ujex audit export-iso42005 --from=ISO --to=ISO');
+                const r = await ap.raw
+                    ?.call?.('auditExportISO42005', { from, to });
+                console.log(JSON.stringify(r ?? { note: 'invoke auditExportISO42005 via SDK raw' }, null, 2));
+            }
+            else if (sub === 'list') {
+                const limit = flagValue(args, '--limit=');
+                const before = flagValue(args, '--before=');
+                const r = await ap.raw
+                    ?.call?.('listMyAuditEntries', { limit: limit ? Number(limit) : 50, beforeSeq: before ? Number(before) : null });
+                console.log(JSON.stringify(r ?? { note: 'invoke listMyAuditEntries via SDK raw' }, null, 2));
+            }
+            else
+                throw new Error('audit verify|export-aat|export-iso42005|list');
+            break;
+        }
+        case 'identity': {
+            const [sub, agentId] = args;
+            if (sub === 'passport') {
+                if (!agentId)
+                    throw new Error('usage: ujex identity passport <agentId>');
+                const r = await ap.identity.passport({ agentId });
+                console.log(JSON.stringify(r, null, 2));
+            }
+            else
+                throw new Error('identity passport');
+            break;
+        }
+        case 'import': {
+            const [source, file] = args;
+            const sources = ['mem0', 'zep', 'letta'];
+            if (!source || !file || !sources.includes(source)) {
+                throw new Error(`usage: ujex import (${sources.join('|')}) <file.json>`);
+            }
+            const r = await importFile(source, file, async (name, data) => {
+                return ap.raw?.call?.(name, data);
+            });
+            console.log(JSON.stringify(r, null, 2));
+            break;
+        }
+        case 'memory-beads-export': {
+            const [out] = args;
+            if (!out)
+                throw new Error('usage: ujex memory-beads-export <out.jsonl>');
+            const list = await ap.memory.list({});
+            const memories = (list.items ?? [])
+                .map((m) => ({ name: m.name, content: m.content ?? '', createdAt: m.createdAt, updatedAt: m.updatedAt }));
+            const r = exportToBeadsJsonl(memories, out);
+            console.log(`exported ${r.count} rows to ${out}`);
+            break;
+        }
+        case 'memory-beads-import': {
+            const [inp] = args;
+            if (!inp)
+                throw new Error('usage: ujex memory-beads-import <in.jsonl>');
+            const rows = importFromBeadsJsonl(inp);
+            let imported = 0;
+            for (const row of rows) {
+                const w = rowToUjexMemoryWrite(row);
+                try {
+                    await ap.memory.write(w);
+                    imported++;
+                }
+                catch (e) {
+                    console.warn(`skipped ${row.name}:`, e instanceof Error ? e.message : e);
+                }
+            }
+            console.log(`imported ${imported}/${rows.length} memories`);
+            break;
+        }
+        default:
+            console.error(`unknown command: ${cmd}\n${HELP}`);
+            process.exit(2);
+    }
+}
+main().catch((e) => { console.error(e.message || e); process.exit(1); });

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@ujexdev/cli",
+  "version": "0.1.0",
+  "description": "Command-line client for Ujex Postbox, approvals, Recall/Memory, Gateway, tools, and audit exports.",
+  "license": "Apache-2.0",
+  "author": "Ujex <hello@ujex.dev>",
+  "homepage": "https://ujex.dev",
+  "keywords": [
+    "ujex",
+    "postbox",
+    "agents",
+    "audit",
+    "memory",
+    "cli"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "ujex": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js"
+  },
+  "dependencies": {
+    "@ujexdev/audit-chain": "^0.2.0",
+    "@ujexdev/client": "^0.1.0",
+    "firebase": "^12.13.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5.5.4"
+  }
+}