@oathbuild/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @oathbuild/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+OATH is a Transaction Builder for autonomous agents. It builds complete agent transaction flows across MCP, x402 and onchain actions, with authorization built into the execution path.
+
+```bash
+npm install -g @oathbuild/cli
+```
+
+```bash
+oath init
+oath create --scope scope.json
+oath build workflow.json
+oath simulate workflow.json
+oath execute workflow.json
+oath receipts oath.json
+oath revoke oath.json
+```
+
+Keys are read from the environment: `OATH_OWNER_KEY`, `OATH_AGENT_KEY` and, optionally, `OATH_RELAYER_KEY`.
+
+## Links
+
+- Docs: https://oathbuild.net/docs
+- Contract addresses: https://oathbuild.net/docs#/deployments
+- App: https://oathbuild.net/app
+
+MIT licensed.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+// oath — command line for the OATH SDK.
+// Keys are read from the environment only (OATH_OWNER_KEY, OATH_AGENT_KEY, OATH_RELAYER_KEY)
+// and are never written to disk.
+import fs from 'node:fs';
+import { parseArgs } from 'node:util';
+import { privateKeyToAccount } from 'viem/accounts';
+import { Oath, OathBuilder, Policy, Receipts, buildPlan, createOathClient, deployAccount, toJson, fromJson, OathError, BuildError } from '@oathbuild/sdk';
+const CONFIG = 'oath.config.json';
+const HELP = `oath <command>
+
+  init                         write ${CONFIG} (chain, RPC, contract addresses)
+  create --scope <file>        create and sign an OATH        [OATH_OWNER_KEY]  (--out oath.json)
+  inspect <oath.json>          scope, status and remaining budget
+  build <workflow.json>        plan a workflow offline        (--oath oath.json, --out plan.json, --max-calls n)
+  simulate <workflow.json>     simulate every onchain bundle  [OATH_AGENT_KEY]  (--oath oath.json)
+  execute <workflow.json>      execute a workflow             [OATH_AGENT_KEY, optional OATH_RELAYER_KEY]
+  receipts <oath.json>         onchain bundle executions for an OATH
+  revoke <oath.json>           revoke an OATH                 [OATH_OWNER_KEY]
+  contracts                    print the configured contract addresses
+
+Options: --rpc <url>  --chain-id <n>  --addresses <file>  --json`;
+class CliError extends Error {
+}
+const { values: flags, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+        scope: { type: 'string' }, oath: { type: 'string', default: 'oath.json' }, out: { type: 'string' }, 'max-calls': { type: 'string' },
+        rpc: { type: 'string' }, 'chain-id': { type: 'string' }, addresses: { type: 'string' }, json: { type: 'boolean' }, 'commit-receipts': { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+    },
+});
+const [command, arg] = positionals;
+const read = (file, what) => {
+    if (!file)
+        throw new CliError(`Missing ${what}.`);
+    if (!fs.existsSync(file))
+        throw new CliError(`${what} not found: ${file}`);
+    try {
+        return fromJson(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw new CliError(`${file} is not valid JSON.`);
+    }
+};
+const key = (name) => {
+    const v = process.env[name];
+    if (!v)
+        throw new CliError(`Set ${name} in the environment.`);
+    return privateKeyToAccount(v);
+};
+const print = (human, data) => console.log(flags.json ? toJson(data, 2) : human);
+const units = (v) => v.toString();
+function client() {
+    const cfg = fs.existsSync(CONFIG) ? fromJson(fs.readFileSync(CONFIG, 'utf8')) : {};
+    const rpc = flags.rpc ?? cfg.rpc;
+    const addresses = flags.addresses ? read(flags.addresses, 'Addresses file') : cfg.addresses;
+    if (!rpc)
+        throw new CliError(`No RPC configured. Run "oath init --rpc <url> --addresses <file>" or pass --rpc.`);
+    return createOathClient({ chainId: Number(flags['chain-id'] ?? cfg.chainId ?? 4663), rpc, addresses });
+}
+function describe(plan) {
+    const lines = [`plan ${plan.planHash}`, `  requested ${plan.actions.length}   authorized ${plan.actions.filter((a) => a.decision === 'AUTHORIZED').length}   rejected ${plan.rejected.length}   deduplicated ${plan.deduplicated}`,
+        `  transactions: baseline ${plan.baselineTransactions} → ${plan.estimatedTransactions} (removed ${plan.removed})`, '', 'groups'];
+    for (const g of plan.groups)
+        lines.push(`  ${g.id.padEnd(12)} ${g.kind.padEnd(20)} ${g.actions.join(', ')}`);
+    if (plan.rejected.length) {
+        lines.push('', 'rejected');
+        for (const r of plan.rejected)
+            lines.push(`  ${r.id.padEnd(16)} ${r.reason}${r.detail ? `  (${r.detail})` : ''}`);
+    }
+    return lines.join('\n');
+}
+const builder = (c, oath) => {
+    const agent = key('OATH_AGENT_KEY');
+    return new OathBuilder({ client: c, oath, agent, relayer: process.env.OATH_RELAYER_KEY ? key('OATH_RELAYER_KEY') : agent, maxCallsPerBundle: flags['max-calls'] ? Number(flags['max-calls']) : undefined });
+};
+const commands = {
+    async init() {
+        if (!flags.rpc)
+            throw new CliError('Pass --rpc <url>. Add --addresses <file> once the contracts are deployed.');
+        const cfg = { chainId: Number(flags['chain-id'] ?? 4663), rpc: flags.rpc, addresses: flags.addresses ? read(flags.addresses, 'Addresses file') : undefined };
+        fs.writeFileSync(CONFIG, toJson(cfg, 2));
+        print(`wrote ${CONFIG}`, cfg);
+    },
+    async create() {
+        const scope = read(flags.scope, 'Scope file (--scope)');
+        const owner = key('OATH_OWNER_KEY'), c = client();
+        const unsigned = await Oath.create(c, { ...scope, owner: owner.address });
+        const signed = await unsigned.sign(owner);
+        const out = flags.out ?? 'oath.json';
+        fs.writeFileSync(out, toJson(signed, 2));
+        print(`created ${signed.id}\n  account ${signed.account}\n  expires ${new Date(Number(signed.validUntil) * 1000).toISOString()}\n  wrote   ${out}`, signed);
+    },
+    async inspect() {
+        const oath = read(arg, 'OATH file'), c = client();
+        const [status, spend] = await Promise.all([Oath.verify(c, oath), Policy.remainingSpend(c, oath)]);
+        const state = status.revoked ? 'REVOKED' : status.expired ? 'EXPIRED' : status.valid ? 'ACTIVE' : 'INVALID';
+        print([`oath ${oath.id}`, `  status   ${state}${status.validSignature ? '' : '  (signature does not verify)'}`, `  owner    ${oath.owner}`, `  agent    ${oath.agent}`, `  account  ${oath.account}`,
+            `  expires  ${new Date(Number(oath.validUntil) * 1000).toISOString()}`, `  targets  ${oath.targets.map((t) => `${t.target} [${t.selectors.join(' ')}]`).join('\n           ') || 'none'}`,
+            `  services ${oath.services.map((s) => `${s.serviceId} [${s.allowedActions.join(' ')}] max ${units(s.maxSpend)}`).join('\n           ') || 'none'}`,
+            ...spend.map((s) => `  spend    ${s.asset}  ${units(s.spent)} of ${units(s.limit)} used, ${units(s.remaining)} remaining`)].join('\n'), { oath, status, spend });
+    },
+    // Offline: planning needs no chain and no keys.
+    async build() {
+        const actions = read(arg, 'Workflow file'), oath = read(flags.oath, 'OATH file (--oath)');
+        const plan = buildPlan(oath, actions, { maxCallsPerBundle: flags['max-calls'] ? Number(flags['max-calls']) : undefined });
+        if (flags.out)
+            fs.writeFileSync(flags.out, toJson(plan, 2));
+        print(describe(plan) + (flags.out ? `\n\nwrote ${flags.out}` : ''), plan);
+    },
+    async simulate() {
+        const actions = read(arg, 'Workflow file'), oath = read(flags.oath, 'OATH file (--oath)');
+        const plan = await builder(client(), oath).add(actions).build();
+        const sims = await plan.simulate();
+        print(describe(plan.toJSON()) + '\n\nsimulation\n' + sims.map((s) => `  ${s.group.padEnd(12)} ${s.deferred ? `deferred (${s.deferred})` : s.success ? `ok   gas ${s.gasEstimate}${(s.assetDeltas ?? []).filter((d) => d.delta !== 0n).map((d) => `   ${d.asset} ${d.delta > 0n ? '+' : ''}${d.delta}`).join('')}` : `FAIL ${s.revertReason}`}`).join('\n'), { plan, simulations: sims });
+        if (sims.some((s) => !s.success))
+            process.exitCode = 1;
+    },
+    async execute() {
+        const actions = read(arg, 'Workflow file'), oath = read(flags.oath, 'OATH file (--oath)');
+        const plan = await builder(client(), oath).add(actions).build();
+        const result = await plan.execute({ commitReceipts: flags['commit-receipts'] });
+        if (flags.out)
+            fs.writeFileSync(flags.out, toJson({ ...result, results: [...result.results] }, 2));
+        print(describe(plan.toJSON()) + '\n\nexecution\n' + (result.bundles.map((b) => `  ${b.group.padEnd(12)} ${b.status.padEnd(9)} ${b.txHash ?? b.error ?? ''}`).join('\n') || '  no onchain bundles'), { ...result, results: [...result.results] });
+        if (result.bundles.some((b) => b.status !== 'EXECUTED'))
+            process.exitCode = 1;
+    },
+    async receipts() {
+        const oath = read(arg, 'OATH file');
+        const list = await Receipts.get(client(), oath);
+        print(list.map((r) => `${r.txHash}  bundle ${r.bundleHash.slice(0, 18)}…  ${r.succeeded} ok, ${r.failed} failed  block ${r.blockNumber}`).join('\n') || 'no executions', list);
+    },
+    async revoke() {
+        const oath = read(arg, 'OATH file');
+        const hash = await Oath.revoke(client(), oath.id, key('OATH_OWNER_KEY'));
+        print(`revoked ${oath.id}\n  tx ${hash}`, { id: oath.id, txHash: hash });
+    },
+    async contracts() {
+        const c = client();
+        print(Object.entries(c.addresses).map(([k, v]) => `${k.padEnd(22)} ${v}`).join('\n') + `\nchain ${c.chainId}`, { chainId: c.chainId, ...c.addresses });
+    },
+    // Not in the handoff's command list, but needed once before a first OATH can execute.
+    async 'deploy-account'() {
+        const owner = key('OATH_OWNER_KEY');
+        print(`account ${await deployAccount(client(), owner, owner.address)}`, {});
+    },
+};
+if (flags.help || !command) {
+    console.log(HELP);
+    process.exit(command || flags.help ? 0 : 1);
+}
+if (!commands[command]) {
+    console.error(`Unknown command "${command}".\n\n${HELP}`);
+    process.exit(1);
+}
+commands[command]().catch((err) => {
+    const known = err instanceof CliError || err instanceof OathError || err instanceof BuildError;
+    console.error(`error: ${known ? err.message : err?.shortMessage ?? err?.message ?? err}`);
+    process.exit(1);
+});

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@oathbuild/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "OATH command line: create, inspect, build, simulate, execute and revoke OATHs.",
+  "keywords": [
+    "oath",
+    "agents",
+    "transaction-builder",
+    "mcp",
+    "x402",
+    "robinhood-chain",
+    "eip-712"
+  ],
+  "homepage": "https://oathbuild.net/docs",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "oath": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "!dist/*.tsbuildinfo",
+    "!dist/.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@oathbuild/sdk": "0.1.0",
+    "viem": "^2.21.0"
+  }
 }