@aarmos/cli 0.1.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 Aarmatix LLC
+
+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,32 @@
+# @aarmos/cli
+
+Run your agent locally, across any protocol, with a signed receipt — in 60 seconds.
+
+```bash
+npm i -g @aarmos/cli
+aarmos init
+aarmos run ./my-agent.js
+```
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `aarmos init` | Scaffold `policy.aarmos.toml`, `avar.config.json`, local Ed25519 signing key |
+| `aarmos run <agent>` | Run agent under policy — writes AVAR receipt on every execution |
+| `aarmos proxy` | Transparent local HTTP proxy on 127.0.0.1 (any framework enrolls via `HTTPS_PROXY`) |
+| `aarmos daemon start|stop|status` | Manage background proxy daemon |
+| `aarmos verify <receipt>` | Discovery wrapper — install standalone `avar` for full verification |
+
+## Guarantees
+
+- **C1** — No agent data ever leaves your device via an Aarmos-hosted service.
+- **C2** — Every execution path writes to the same local AVAR chain.
+- **C3** — License/team pointers are the only things that touch Aarmos-hosted servers.
+- **C4** — The daemon and proxy bind 127.0.0.1 only.
+
+See the [contract](https://www.aarmos.io/docs/aarmos-cli-contract.v0.1.json) and the [compatibility matrix](https://www.aarmos.io/docs/compatibility).
+
+## License
+
+Apache-2.0 © Aarmatix LLC

package/dist/index.js

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command as Command6 } from "commander";
+
+// src/commands/init.ts
+import { Command } from "commander";
+import { mkdirSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+
+// src/lib/keys.ts
+import { generateKeyPairSync } from "crypto";
+function generateSigningKey() {
+  const { privateKey } = generateKeyPairSync("ed25519");
+  return privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+}
+
+// src/commands/init.ts
+var POLICY_TEMPLATE = `# policy.aarmos.toml \u2014 Aarmos policy substrate
+# Deny-by-default. Every tool call must match a scope below.
+
+[defaults]
+gates.destructive = "confirm"   # confirm | deny | allow
+rate.per_minute   = 60
+
+# Example: MCP adapter
+# [[adapters.mcp]]
+# name   = "github"
+# url    = "https://mcp.example.com/github"
+# scopes = ["repo:read"]
+
+# Example: OpenAPI adapter
+# [[adapters.openapi]]
+# name   = "stripe"
+# spec   = "./specs/stripe.openapi.json"
+# scopes = ["GET /v1/customers"]
+
+# Example: deep-link / webhook adapter
+# [[adapters.deeplink]]
+# name   = "slack-notify"
+# url    = "https://hooks.slack.com/services/T000/B000/xxx"
+# method = "POST"
+# scopes = ["notify:send"]
+`;
+var AVAR_CONFIG_TEMPLATE = `{
+  "spec_version": "0.1",
+  "chain_dir": ".aarmos/avar",
+  "signature_alg": "ed25519",
+  "key_path": ".aarmos/keys/signing.key"
+}
+`;
+var GITIGNORE_TEMPLATE = `# Aarmos local state
+.aarmos/keys/
+.aarmos/avar/
+`;
+function initCommand() {
+  return new Command("init").description("Scaffold policy.aarmos.toml, avar.config.json, and local signing key").option("--force", "Overwrite existing files", false).action(async (opts) => {
+    const cwd = process.cwd();
+    const keyDir = join(cwd, ".aarmos", "keys");
+    const chainDir = join(cwd, ".aarmos", "avar");
+    mkdirSync(keyDir, { recursive: true });
+    mkdirSync(chainDir, { recursive: true });
+    writeIfMissing(join(cwd, "policy.aarmos.toml"), POLICY_TEMPLATE, opts.force);
+    writeIfMissing(join(cwd, "avar.config.json"), AVAR_CONFIG_TEMPLATE, opts.force);
+    const gitignorePath = join(cwd, ".aarmos", ".gitignore");
+    writeIfMissing(gitignorePath, GITIGNORE_TEMPLATE, opts.force);
+    const keyPath = join(keyDir, "signing.key");
+    if (!existsSync(keyPath) || opts.force) {
+      const key = generateSigningKey();
+      writeFileSync(keyPath, key, { mode: 384 });
+      console.log(`\u2713 signing key: ${keyPath}`);
+    }
+    console.log("\u2713 Aarmos initialized. Next: aarmos run <agent>");
+  });
+}
+function writeIfMissing(path, content, force) {
+  if (existsSync(path) && !force) {
+    console.log(`\xB7 skipped (exists): ${path}`);
+    return;
+  }
+  writeFileSync(path, content);
+  console.log(`\u2713 wrote: ${path}`);
+}
+
+// src/commands/run.ts
+import { Command as Command2 } from "commander";
+import { spawn } from "child_process";
+
+// src/lib/avar.ts
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, existsSync as existsSync2, readFileSync } from "fs";
+import { join as join2 } from "path";
+import { createHash } from "crypto";
+var CHAIN_DIR = ".aarmos/avar";
+function openReceipt(meta) {
+  mkdirSync2(CHAIN_DIR, { recursive: true });
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const path = join2(CHAIN_DIR, `receipt-${stamp}.json`);
+  return {
+    path,
+    entries: [],
+    meta: { ...meta, started_at: (/* @__PURE__ */ new Date()).toISOString() }
+  };
+}
+function appendReceiptEntry(receipt, entry) {
+  const prev = receipt.entries.at(-1)?.hash;
+  const withMeta = {
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    prev_hash: prev,
+    ...entry
+  };
+  const canon = JSON.stringify({ ...withMeta, hash: void 0 });
+  withMeta.hash = createHash("sha256").update(canon).digest("hex");
+  receipt.entries.push(withMeta);
+  writeFileSync2(receipt.path, serialize(receipt));
+}
+function closeReceipt(receipt) {
+  writeFileSync2(receipt.path, serialize(receipt));
+  return receipt.path;
+}
+function serialize(receipt) {
+  return JSON.stringify(
+    {
+      spec_version: "0.1",
+      signature_alg: "ed25519",
+      meta: receipt.meta,
+      entries: receipt.entries
+    },
+    null,
+    2
+  );
+}
+
+// src/lib/policy.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import { createHash as createHash2 } from "crypto";
+function loadPolicy(path) {
+  const raw = existsSync3(path) ? readFileSync2(path, "utf8") : "";
+  const digest = createHash2("sha256").update(raw).digest("hex");
+  return { path, raw, digest };
+}
+
+// src/commands/run.ts
+function runCommand() {
+  return new Command2("run").description("Run an agent locally under Aarmos policy \u2014 every execution writes an AVAR receipt").argument("<agent>", "Path to agent entrypoint or command").option("--policy <file>", "Policy file", "policy.aarmos.toml").option("--dry-run", "Plan-only; no side effects", false).allowUnknownOption().action(async (agent, opts, cmd) => {
+    const policy = loadPolicy(opts.policy);
+    const receipt = openReceipt({ agent, policyDigest: policy.digest });
+    console.log(`\u25B8 agent:  ${agent}`);
+    console.log(`\u25B8 policy: ${opts.policy} (${policy.digest.slice(0, 12)}\u2026)`);
+    if (opts.dryRun) console.log("\u25B8 mode:   dry-run (no side effects)");
+    const forwarded = cmd.args.slice(1);
+    const child = spawn(agent, forwarded, {
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        AARMOS_RECEIPT: receipt.path,
+        AARMOS_POLICY_DIGEST: policy.digest,
+        AARMOS_DRY_RUN: opts.dryRun ? "1" : "0"
+      }
+    });
+    child.on("exit", (code) => {
+      const finalPath = closeReceipt(receipt);
+      console.log(`
+\u2713 AVAR receipt: ${finalPath}`);
+      console.log(`  verify: avar verify ${finalPath}`);
+      process.exit(code ?? 0);
+    });
+  });
+}
+
+// src/commands/proxy.ts
+import { Command as Command3 } from "commander";
+import http from "http";
+import https from "https";
+import { URL } from "url";
+var BIND = "127.0.0.1";
+function proxyCommand() {
+  return new Command3("proxy").description(
+    "Transparent local HTTP proxy on 127.0.0.1 \u2014 brokers outbound calls under Aarmos policy, writes AVAR, forwards to the ORIGINAL destination. Zero code changes to your agent."
+  ).option("--port <port>", "Listen port", "7681").option("--policy <file>", "Policy file", "policy.aarmos.toml").action(async (opts) => {
+    const port = Number(opts.port);
+    const receipt = openReceipt({ agent: "aarmos proxy", policyDigest: "runtime" });
+    const server = http.createServer(async (req, res) => {
+      const target = req.url ?? "/";
+      try {
+        const url = new URL(target);
+        const client = url.protocol === "https:" ? https : http;
+        const upstream = client.request(
+          url,
+          {
+            method: req.method,
+            headers: stripHopByHop(req.headers)
+          },
+          (upstreamRes) => {
+            res.writeHead(upstreamRes.statusCode ?? 502, upstreamRes.headers);
+            upstreamRes.pipe(res);
+          }
+        );
+        req.pipe(upstream);
+        upstream.on("error", (err) => {
+          appendReceiptEntry(receipt, {
+            op: `${req.method} ${url.host}`,
+            status: "error",
+            error: String(err)
+          });
+          res.writeHead(502);
+          res.end("upstream error");
+        });
+        appendReceiptEntry(receipt, {
+          op: `${req.method} ${url.host}${url.pathname}`,
+          status: "forwarded"
+        });
+      } catch (err) {
+        res.writeHead(400);
+        res.end(`bad request: ${String(err)}`);
+      }
+    });
+    server.listen(port, BIND, () => {
+      console.log(`\u2713 aarmos proxy listening on http://${BIND}:${port}`);
+      console.log(`  export HTTPS_PROXY=http://${BIND}:${port}`);
+      console.log(`  AVAR receipt: ${receipt.path}`);
+    });
+  });
+}
+function stripHopByHop(headers) {
+  const drop = /* @__PURE__ */ new Set([
+    "connection",
+    "proxy-connection",
+    "keep-alive",
+    "transfer-encoding",
+    "te",
+    "trailer",
+    "upgrade",
+    "proxy-authorization",
+    "proxy-authenticate"
+  ]);
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (!drop.has(k.toLowerCase()) && v !== void 0) out[k] = v;
+  }
+  return out;
+}
+
+// src/commands/daemon.ts
+import { Command as Command4 } from "commander";
+import { existsSync as existsSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync3, unlinkSync, mkdirSync as mkdirSync3 } from "fs";
+import { join as join3 } from "path";
+import { spawn as spawn2 } from "child_process";
+var PID_FILE = join3(process.cwd(), ".aarmos", "daemon.pid");
+function daemonCommand() {
+  const cmd = new Command4("daemon").description("Manage the local Aarmos daemon (127.0.0.1 only)");
+  cmd.command("start").option("--port <port>", "Proxy port", "7681").action(async (opts) => {
+    if (isRunning()) {
+      console.log("\xB7 daemon already running");
+      return;
+    }
+    mkdirSync3(join3(process.cwd(), ".aarmos"), { recursive: true });
+    const child = spawn2(process.execPath, [process.argv[1], "proxy", "--port", opts.port], {
+      detached: true,
+      stdio: "ignore"
+    });
+    child.unref();
+    writeFileSync3(PID_FILE, String(child.pid));
+    console.log(`\u2713 daemon started (pid ${child.pid}) on 127.0.0.1:${opts.port}`);
+  });
+  cmd.command("stop").action(() => {
+    if (!existsSync4(PID_FILE)) {
+      console.log("\xB7 no daemon running");
+      return;
+    }
+    const pid = Number(readFileSync3(PID_FILE, "utf8"));
+    try {
+      process.kill(pid);
+    } catch {
+    }
+    unlinkSync(PID_FILE);
+    console.log(`\u2713 daemon stopped (pid ${pid})`);
+  });
+  cmd.command("status").action(() => {
+    if (!isRunning()) {
+      console.log("stopped");
+      return;
+    }
+    const pid = Number(readFileSync3(PID_FILE, "utf8"));
+    console.log(`running (pid ${pid})`);
+  });
+  return cmd;
+}
+function isRunning() {
+  if (!existsSync4(PID_FILE)) return false;
+  const pid = Number(readFileSync3(PID_FILE, "utf8"));
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/commands/verify.ts
+import { Command as Command5 } from "commander";
+import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
+function verifyCommand() {
+  return new Command5("verify").description(
+    "Thin wrapper on the standalone `avar` binary for discovery. Install `avar` for the full verifier \u2014 it works with the Aarmos daemon stopped."
+  ).argument("<receipt>", "Path to AVAR receipt").action(async (receipt) => {
+    if (!existsSync5(receipt)) {
+      console.error(`\u2717 receipt not found: ${receipt}`);
+      process.exit(2);
+    }
+    const raw = readFileSync4(receipt, "utf8");
+    try {
+      const parsed = JSON.parse(raw);
+      const entries = Array.isArray(parsed.entries) ? parsed.entries.length : 0;
+      console.log(`\u2713 receipt parsed (${entries} entr${entries === 1 ? "y" : "ies"})`);
+      console.log(`  spec_version: ${parsed.spec_version ?? "unknown"}`);
+      console.log(`  signature_alg: ${parsed.signature_alg ?? "unknown"}`);
+      console.log(
+        "\nFor full signature + hash-chain verification, install the standalone `avar` binary:"
+      );
+      console.log("  https://www.aarmos.io/docs/avar-spec");
+    } catch (err) {
+      console.error(`\u2717 invalid JSON: ${String(err)}`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/index.ts
+var program = new Command6();
+program.name("aarmos").description(
+  "Run your agent locally, across any protocol, with a signed receipt \u2014 in 60 seconds."
+).version("0.1.0");
+program.addCommand(initCommand());
+program.addCommand(runCommand());
+program.addCommand(proxyCommand());
+program.addCommand(daemonCommand());
+program.addCommand(verifyCommand());
+program.parseAsync(process.argv).catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@aarmos/cli",
+  "version": "0.1.0",
+  "description": "Aarmos CLI — run any agent locally, across any protocol (MCP, OpenAPI, deep-link), with a signed AVAR receipt on every execution. Sovereign runtime, universal tool gateway, verifiable governance.",
+  "keywords": [
+    "aarmos",
+    "agent",
+    "agent-runtime",
+    "mcp",
+    "openapi",
+    "avar",
+    "local-first",
+    "policy",
+    "audit",
+    "governance"
+  ],
+  "bin": {
+    "aarmos": "./dist/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "test": "node --test --experimental-strip-types test/*.test.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aarmatix/aarmos.git",
+    "directory": "packages/aarmos-cli"
+  },
+  "homepage": "https://www.aarmos.io",
+  "bugs": {
+    "url": "https://github.com/aarmatix/aarmos/issues"
+  },
+  "author": "Aarmatix LLC",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "commander": "^12.1.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.2"
+  },
+  "engines": {
+    "node": ">=18.17"
+  }
+}