@arbiterhq/cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.1.0 — 2026-06-28
+
+First public npm release under **`@arbiterhq/cli`**. The CLI binary remains **`arbiter`**; only the npm scope changed from the previously planned `@arbiter` org.
+
+### Added
+
+- `arbiter login` — save API credentials locally
+- `arbiter init` — create `arbiter.yaml` (optional `--from-remote`)
+- `arbiter validate` — local manifest validation
+- `arbiter plan` — manifest diff against remote workspace
+- `arbiter apply` — sync manifest (`--yes` for CI)
+- `arbiter drift` — workspace drift and adoption suggestions
+- `arbiter status` — endpoint, manifest version, state signature
+- `arbiter whoami` — credential session context
+
+### Dependencies
+
+- Requires `@arbiterhq/sdk@^0.2.0` (publish SDK before CLI)

package/README.md

@@ -0,0 +1,89 @@
+# @arbiterhq/cli
+
+Official `arbiter` command line interface. Stateless wrapper over [`@arbiterhq/sdk`](../sdk).
+
+## Install
+
+```bash
+npm install -g @arbiterhq/cli
+```
+
+Requires Node.js 18+. The CLI depends on `@arbiterhq/sdk` from npm — install the SDK first if you use it directly in agent code:
+
+```bash
+npm install @arbiterhq/sdk
+```
+
+### Local development (monorepo contributors)
+
+```bash
+cd packages/cli
+npm install
+npm run build
+npm link
+```
+
+## Authentication
+
+```bash
+arbiter login
+# or
+export ARBITER_API_KEY=your_key
+export ARBITER_BASE_URL=https://api.arbitertrust.com
+```
+
+Credentials are stored at `~/.config/arbiter/credentials.json`. `ARBITER_API_KEY` takes precedence over the file.
+
+### Base URL resolution
+
+1. `ARBITER_BASE_URL` environment variable
+2. `baseUrl` saved in credentials file (set via `arbiter login --base-url`)
+3. Production default: `https://api.arbitertrust.com`
+
+**Local development:** `export ARBITER_BASE_URL=http://localhost:3001` or `arbiter login --base-url http://localhost:3001`
+
+`login` performs a local filesystem write only — no network validation.
+
+## Commands
+
+| Command | Network | Description |
+|---------|---------|-------------|
+| `arbiter login` | No | Save credentials locally |
+| `arbiter init` | Optional (`--from-remote`) | Create `arbiter.yaml` |
+| `arbiter validate` | No | Local structural validation |
+| `arbiter plan` | Yes | Diff manifest vs remote |
+| `arbiter apply` | Yes | Sync manifest to remote |
+| `arbiter apply --yes` | Yes | Non-interactive apply for CI |
+| `arbiter drift` | Yes | Drift + adoption suggestions |
+| `arbiter status` | Yes | Endpoint, manifest version, signature |
+| `arbiter whoami` | No | Session context |
+
+## Exit codes
+
+| Code | `plan` / `drift` | Other commands |
+|------|------------------|----------------|
+| `0` | In sync / success | Success |
+| `1` | Error | Error |
+| `2` | Drift or pending changes | — |
+
+## CI example
+
+```bash
+arbiter validate
+arbiter plan
+arbiter apply --yes
+```
+
+## Options
+
+Global manifest path override:
+
+```bash
+arbiter plan --manifest ./config/arbiter.yaml
+```
+
+Disable colors in pipelines:
+
+```bash
+NO_COLOR=1 arbiter plan
+```

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,992 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/commands/apply.ts
+import readline from "readline/promises";
+import { stdin as input, stdout as output } from "process";
+import { ArbiterError } from "@arbiterhq/sdk";
+
+// src/config/client.ts
+import { ArbiterAdmin } from "@arbiterhq/sdk";
+
+// src/config/credentials.ts
+import fs from "fs";
+import path2 from "path";
+
+// src/config/paths.ts
+import os from "os";
+import path from "path";
+var CREDENTIALS_DIR = path.join(os.homedir(), ".config", "arbiter");
+var CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, "credentials.json");
+var DEFAULT_MANIFEST_FILE = "arbiter.yaml";
+var DEFAULT_BASE_URL = "https://api.arbitertrust.com";
+
+// src/config/credentials.ts
+function loadCredentialsFile() {
+  if (!fs.existsSync(CREDENTIALS_FILE)) {
+    return null;
+  }
+  const raw = fs.readFileSync(CREDENTIALS_FILE, "utf8");
+  const parsed = JSON.parse(raw);
+  if (typeof parsed.apiKey !== "string" || parsed.apiKey.length === 0) {
+    throw new Error(`Invalid credentials file at ${CREDENTIALS_FILE}: apiKey is required`);
+  }
+  return parsed;
+}
+function saveCredentialsFile(credentials) {
+  fs.mkdirSync(CREDENTIALS_DIR, { recursive: true });
+  const payload = {
+    apiKey: credentials.apiKey,
+    baseUrl: credentials.baseUrl ?? DEFAULT_BASE_URL
+  };
+  if (credentials.workspace !== void 0) {
+    payload.workspace = credentials.workspace;
+  }
+  if (credentials.environment !== void 0) {
+    payload.environment = credentials.environment;
+  }
+  fs.writeFileSync(CREDENTIALS_FILE, `${JSON.stringify(payload, null, 2)}
+`, "utf8");
+}
+function resolveSession() {
+  const envApiKey = process.env.ARBITER_API_KEY;
+  const fileCredentials = loadCredentialsFile();
+  const apiKey = envApiKey ?? fileCredentials?.apiKey;
+  if (!apiKey) {
+    throw new Error(
+      "No API key found. Run `arbiter login` or set ARBITER_API_KEY."
+    );
+  }
+  const baseUrl = process.env.ARBITER_BASE_URL ?? fileCredentials?.baseUrl ?? DEFAULT_BASE_URL;
+  let source = "file";
+  if (envApiKey && fileCredentials?.apiKey) {
+    source = "env+file";
+  } else if (envApiKey) {
+    source = "env";
+  }
+  return {
+    apiKey,
+    baseUrl,
+    workspace: fileCredentials?.workspace ?? null,
+    environment: fileCredentials?.environment ?? null,
+    source
+  };
+}
+function maskApiKey(apiKey) {
+  if (apiKey.length <= 8) {
+    return "********";
+  }
+  return `${apiKey.slice(0, 4)}...${apiKey.slice(-4)}`;
+}
+function credentialsFilePath() {
+  return path2.normalize(CREDENTIALS_FILE);
+}
+
+// src/config/client.ts
+function createArbiterClient() {
+  const session = resolveSession();
+  return new ArbiterAdmin({
+    apiKey: session.apiKey,
+    baseUrl: session.baseUrl
+  });
+}
+
+// src/config/manifest.ts
+import fs2 from "fs";
+import path3 from "path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+
+// src/config/manifestSchema.ts
+import { z } from "zod";
+var SNAKE_CASE_ACTION = /^[a-z][a-z0-9_]*$/;
+var RESOURCE_SOURCES = ["dashboard", "sdk", "discovered"];
+var RESOURCE_MANAGEMENTS = ["dashboard", "sdk", "manifest", "discovered"];
+var PERMISSION_STATUSES = [
+  "pending_review",
+  "allowed",
+  "denied",
+  "approval_required"
+];
+var AGENT_STATUSES = [
+  "pending_review",
+  "active",
+  "disabled",
+  "expired",
+  "archived"
+];
+var RISK_TIERS = ["low", "medium", "high", "critical"];
+var OWNER_TYPES = ["user", "team", "service_account"];
+var POLICY_OPERATORS = [
+  ">",
+  ">=",
+  "<",
+  "<=",
+  "=",
+  "==",
+  "!=",
+  "contains",
+  "not_contains",
+  "starts_with",
+  "ends_with",
+  "in",
+  "not_in",
+  "exists",
+  "not_exists",
+  "is_null",
+  "is_not_null",
+  "between",
+  "not_between"
+];
+var POLICY_DECISIONS = ["allow", "deny", "hold"];
+var POLICY_CONDITION_OPERATORS = ["AND", "OR"];
+var VALUELESS_OPERATORS = /* @__PURE__ */ new Set(["exists", "not_exists", "is_null", "is_not_null"]);
+var PolicyScalarValueSchema = z.union([z.number(), z.string(), z.boolean(), z.null()]);
+var PolicyArrayValueSchema = z.array(PolicyScalarValueSchema).max(100);
+var PolicyValueSchema = z.union([PolicyScalarValueSchema, PolicyArrayValueSchema]);
+var ManifestOwnerSchema = z.object({
+  slug: z.string().min(1),
+  type: z.enum(OWNER_TYPES)
+});
+var GrantMutationSchema = z.object({
+  action: z.string().min(1).regex(SNAKE_CASE_ACTION, "Action must be snake_case"),
+  grantedBy: z.string().min(1).optional(),
+  grantedReason: z.string().max(500).optional()
+});
+var ManifestAgentSchema = z.object({
+  externalId: z.string().min(1).optional(),
+  name: z.string().min(1, "Agent name is required"),
+  description: z.string().optional(),
+  source: z.enum(RESOURCE_SOURCES).optional(),
+  management: z.enum(RESOURCE_MANAGEMENTS).optional(),
+  owner: ManifestOwnerSchema.optional(),
+  ownerSlug: z.string().min(1).optional(),
+  ownerType: z.enum(OWNER_TYPES).optional(),
+  riskTier: z.enum(RISK_TIERS).optional(),
+  status: z.enum(AGENT_STATUSES).optional(),
+  expiresAt: z.string().datetime().optional(),
+  approvedBy: z.string().optional(),
+  grants: z.array(GrantMutationSchema).optional()
+});
+var ManifestPermissionSchema = z.object({
+  action: z.string().min(1).regex(SNAKE_CASE_ACTION, "Action must be snake_case"),
+  description: z.string().optional(),
+  status: z.enum(PERMISSION_STATUSES).optional(),
+  source: z.enum(RESOURCE_SOURCES).optional(),
+  management: z.enum(RESOURCE_MANAGEMENTS).optional(),
+  assignedAgents: z.array(z.string().min(1)).optional(),
+  displayName: z.string().nullable().optional(),
+  category: z.string().nullable().optional(),
+  documentation: z.string().nullable().optional(),
+  tags: z.array(z.string()).nullable().optional(),
+  metadata: z.record(z.unknown()).nullable().optional()
+});
+var PolicyConditionSchema = z.object({
+  field: z.string().min(1).max(256),
+  operator: z.enum(POLICY_OPERATORS),
+  value: PolicyValueSchema.optional(),
+  type: z.string().nullable().optional()
+}).superRefine((condition, ctx) => {
+  const requiresValue = !VALUELESS_OPERATORS.has(condition.operator);
+  if (requiresValue && condition.value === void 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: `Operator "${condition.operator}" requires a value`,
+      path: ["value"]
+    });
+  }
+  if ((condition.operator === "in" || condition.operator === "not_in") && condition.value !== void 0 && !Array.isArray(condition.value)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: `Operator "${condition.operator}" requires an array value`,
+      path: ["value"]
+    });
+  }
+});
+var ManifestPolicySchema = z.object({
+  id: z.string().min(1).optional(),
+  action: z.string().regex(SNAKE_CASE_ACTION, "Action must be snake_case"),
+  field: z.string().min(1).optional(),
+  operator: z.enum(POLICY_OPERATORS).optional(),
+  value: PolicyValueSchema.optional(),
+  conditions: z.array(PolicyConditionSchema).min(1).optional(),
+  conditionOperator: z.enum(POLICY_CONDITION_OPERATORS).optional(),
+  priority: z.number().int().optional(),
+  displayName: z.string().min(1).optional(),
+  decision: z.enum(POLICY_DECISIONS),
+  source: z.enum(RESOURCE_SOURCES).optional(),
+  management: z.enum(RESOURCE_MANAGEMENTS).optional()
+}).superRefine((data, ctx) => {
+  const hasLegacy = data.field !== void 0 && data.operator !== void 0 && data.value !== void 0;
+  const hasConditions = (data.conditions?.length ?? 0) > 0;
+  if (!hasLegacy && !hasConditions) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "Manifest policy requires field/operator/value or conditions",
+      path: ["conditions"]
+    });
+  }
+});
+var ManifestWorkspaceSchema = z.object({
+  agents: z.array(ManifestAgentSchema),
+  permissions: z.array(ManifestPermissionSchema),
+  policies: z.array(ManifestPolicySchema)
+});
+var ManifestDocumentSchema = z.object({
+  apiVersion: z.string().optional(),
+  kind: z.string().optional(),
+  metadata: z.object({
+    name: z.string().optional(),
+    environment: z.string().optional()
+  }).optional(),
+  spec: ManifestWorkspaceSchema.optional(),
+  agents: z.array(ManifestAgentSchema).optional(),
+  permissions: z.array(ManifestPermissionSchema).optional(),
+  policies: z.array(ManifestPolicySchema).optional()
+}).superRefine((value, ctx) => {
+  const hasSpec = value.spec !== void 0;
+  const hasRoot = value.agents !== void 0 || value.permissions !== void 0 || value.policies !== void 0;
+  if (!hasSpec && !hasRoot) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "Manifest must define spec.agents or root-level agents"
+    });
+  }
+});
+
+// src/config/manifestAdapter.ts
+function toSdkManifest(workspace) {
+  return {
+    agents: workspace.agents.map((agent) => ({ ...agent })),
+    permissions: workspace.permissions.map((permission) => ({ ...permission })),
+    policies: workspace.policies.map((policy) => ({ ...policy }))
+  };
+}
+
+// src/config/manifest.ts
+function resolveManifestPath(manifestFlag) {
+  return path3.resolve(process.cwd(), manifestFlag ?? DEFAULT_MANIFEST_FILE);
+}
+function loadManifestFile(manifestPath) {
+  if (!fs2.existsSync(manifestPath)) {
+    throw new Error(`Manifest not found: ${manifestPath}`);
+  }
+  const content = fs2.readFileSync(manifestPath, "utf8");
+  return parseManifestContent(content, manifestPath);
+}
+function parseManifestContent(content, manifestPath) {
+  let document;
+  try {
+    document = parseYaml(content);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid YAML";
+    throw new Error(`${manifestPath}: ${message}`);
+  }
+  const parsed = ManifestDocumentSchema.safeParse(document);
+  if (!parsed.success) {
+    const issues = formatZodIssues(parsed.error.issues);
+    throw new Error(`Manifest validation failed:
+${issues.join("\n")}`);
+  }
+  const doc = parsed.data;
+  const workspaceInput = doc.spec ?? {
+    agents: doc.agents ?? [],
+    permissions: doc.permissions ?? [],
+    policies: doc.policies ?? []
+  };
+  const workspace = toSdkManifest(ManifestWorkspaceSchema.parse(workspaceInput));
+  return {
+    path: manifestPath,
+    workspace,
+    apiVersion: doc.apiVersion ?? null,
+    metadataName: doc.metadata?.name ?? null,
+    environment: doc.metadata?.environment ?? null
+  };
+}
+function validateManifestFile(manifestPath) {
+  if (!fs2.existsSync(manifestPath)) {
+    return [{ path: manifestPath, message: "File not found", line: null }];
+  }
+  const content = fs2.readFileSync(manifestPath, "utf8");
+  try {
+    parseYaml(content);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid YAML";
+    const line = extractYamlLine(message);
+    return [{ path: manifestPath, message, line }];
+  }
+  let document;
+  try {
+    document = parseYaml(content);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid YAML";
+    return [{ path: manifestPath, message, line: extractYamlLine(message) }];
+  }
+  const parsed = ManifestDocumentSchema.safeParse(document);
+  if (!parsed.success) {
+    return parsed.error.issues.map((issue) => ({
+      path: issue.path.join(".") || "root",
+      message: issue.message,
+      line: null
+    }));
+  }
+  const doc = parsed.data;
+  const workspaceInput = doc.spec ?? {
+    agents: doc.agents ?? [],
+    permissions: doc.permissions ?? [],
+    policies: doc.policies ?? []
+  };
+  const workspaceParsed = ManifestWorkspaceSchema.safeParse(workspaceInput);
+  if (!workspaceParsed.success) {
+    return workspaceParsed.error.issues.map((issue) => ({
+      path: issue.path.join(".") || "root",
+      message: issue.message,
+      line: null
+    }));
+  }
+  return [];
+}
+function formatZodIssues(issues) {
+  return issues.map((issue) => {
+    const location = issue.path.length > 0 ? issue.path.join(".") : "root";
+    return `  - ${location}: ${issue.message}`;
+  });
+}
+function extractYamlLine(message) {
+  const match = message.match(/at line (\d+)/i);
+  if (!match?.[1]) {
+    return null;
+  }
+  return Number.parseInt(match[1], 10);
+}
+function starterManifestTemplate() {
+  const document = {
+    apiVersion: "arbiter.dev/v1",
+    kind: "WorkspaceGovernance",
+    metadata: {
+      name: "my-workspace",
+      environment: "development"
+    },
+    spec: {
+      agents: [
+        {
+          externalId: "finance-agent",
+          name: "finance-agent",
+          description: "Handles payment operations"
+        }
+      ],
+      permissions: [
+        {
+          action: "send_payment",
+          status: "approval_required"
+        }
+      ],
+      policies: [
+        {
+          id: "payment-amount-hold",
+          action: "send_payment",
+          field: "amount",
+          operator: ">",
+          value: 1e3,
+          decision: "hold"
+        }
+      ]
+    }
+  };
+  return stringifyYaml(document, { indent: 2 });
+}
+function workspaceToManifestDocument(workspace, metadata) {
+  const document = {
+    apiVersion: "arbiter.dev/v1",
+    kind: "WorkspaceGovernance",
+    metadata: {
+      name: metadata?.name ?? "imported-workspace",
+      environment: metadata?.environment ?? "production"
+    },
+    spec: workspace
+  };
+  return stringifyYaml(document, { indent: 2 });
+}
+
+// src/output/format.ts
+var ANSI = {
+  reset: "\x1B[0m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  red: "\x1B[31m",
+  cyan: "\x1B[36m",
+  magenta: "\x1B[35m",
+  dim: "\x1B[2m",
+  bold: "\x1B[1m"
+};
+function isColorEnabled() {
+  if (process.env.NO_COLOR !== void 0) {
+    return false;
+  }
+  return Boolean(process.stdout.isTTY);
+}
+function colorize(text, color) {
+  if (!isColorEnabled()) {
+    return text;
+  }
+  return `${ANSI[color]}${text}${ANSI.reset}`;
+}
+function writeLine(line) {
+  process.stdout.write(`${line}
+`);
+}
+function writeError(line) {
+  process.stderr.write(`${line}
+`);
+}
+function divider() {
+  writeLine("\u2500".repeat(64));
+}
+
+// src/output/plan.ts
+function renderPlanResult(result, options) {
+  writeLine(colorize("Arbiter Plan", "bold"));
+  writeLine(`Manifest: ${options.manifestPath}`);
+  divider();
+  if (!result.drift) {
+    writeLine(colorize("No changes. Workspace is in sync.", "green"));
+    return;
+  }
+  const deep = result;
+  for (const item of deep.changes.create) {
+    writeLine(formatChangeLine("[+]", "CREATE", item, "green"));
+  }
+  for (const item of deep.changes.update) {
+    writeLine(formatChangeLine("[~]", "UPDATE", item, "yellow"));
+  }
+  for (const item of deep.changes.archive) {
+    writeLine(formatChangeLine("[-]", "ARCHIVE", item, "red"));
+  }
+  for (const suggestion of deep.adoptionSuggestions) {
+    writeLine(formatAdoptLine(suggestion));
+  }
+  if (options.verbose) {
+    const unchangedTotal = deep.summary.agents.unchanged + deep.summary.permissions.unchanged + deep.summary.policies.unchanged;
+    if (unchangedTotal > 0) {
+      writeLine(
+        colorize(
+          `[=] UNCHANGED ${unchangedTotal} resources (agents: ${deep.summary.agents.unchanged}, permissions: ${deep.summary.permissions.unchanged}, policies: ${deep.summary.policies.unchanged})`,
+          "dim"
+        )
+      );
+    }
+  }
+  divider();
+  writeLine(
+    `Plan: ${deep.summary.agents.create + deep.summary.permissions.create + deep.summary.policies.create} to add, ${deep.summary.agents.update + deep.summary.permissions.update + deep.summary.policies.update} to change, ${deep.summary.agents.archive + deep.summary.permissions.archive + deep.summary.policies.archive} to archive, ${deep.adoptionSuggestions.length} adopt suggestions.`
+  );
+}
+function planHasActionableChanges(result) {
+  if (!result.drift) {
+    return false;
+  }
+  const deep = result;
+  const summary = deep.summary;
+  const mutations = summary.agents.create + summary.agents.update + summary.agents.archive + summary.permissions.create + summary.permissions.update + summary.permissions.archive + summary.policies.create + summary.policies.update + summary.policies.archive;
+  return mutations > 0 || deep.adoptionSuggestions.length > 0;
+}
+function formatChangeLine(indicator, verb, item, color) {
+  const resourceType = capitalize(item.type);
+  const identifier = resourceIdentifier(item);
+  return colorize(`${indicator} ${verb} ${resourceType} ${identifier}`, color);
+}
+function formatAdoptLine(suggestion) {
+  const resourceType = capitalize(suggestion.type);
+  const identifier = adoptIdentifier(suggestion);
+  return colorize(`[?] ADOPT ${resourceType} ${identifier}`, "cyan");
+}
+function resourceIdentifier(item) {
+  if (item.type === "agent" && item.externalId) {
+    return item.externalId;
+  }
+  if (item.type === "permission" && item.action) {
+    return item.action;
+  }
+  if (item.type === "policy" && item.id) {
+    return item.id;
+  }
+  if (item.type === "grant" && item.externalId && item.action) {
+    return `${item.externalId} -> ${item.action}`;
+  }
+  if (item.externalId) {
+    return item.externalId;
+  }
+  if (item.action) {
+    return item.action;
+  }
+  if (item.id) {
+    return item.id;
+  }
+  return "unknown";
+}
+function adoptIdentifier(suggestion) {
+  if (suggestion.externalId) {
+    return suggestion.externalId;
+  }
+  if (suggestion.action) {
+    return suggestion.action;
+  }
+  if (suggestion.id) {
+    return suggestion.id;
+  }
+  return "unknown";
+}
+function capitalize(value) {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+// src/commands/apply.ts
+async function runApply(options) {
+  try {
+    const manifestPath = resolveManifestPath(options.manifest);
+    const loaded = loadManifestFile(manifestPath);
+    const arbiter = createArbiterClient();
+    const planResult = await arbiter.plan(loaded.workspace);
+    renderPlanResult(planResult, {
+      verbose: options.verbose === true,
+      manifestPath
+    });
+    if (!options.yes) {
+      const confirmed = await promptForConfirmation();
+      if (!confirmed) {
+        writeLine(colorize("Apply cancelled.", "yellow"));
+        return 0;
+      }
+    }
+    const applyResult = await arbiter.syncRegistryManifest(loaded.workspace);
+    divider();
+    writeLine(colorize("Apply complete.", "green"));
+    writeLine(
+      `Summary: agents(+${applyResult.summary.agents.created}/~${applyResult.summary.agents.updated}/-${applyResult.summary.agents.archived}), permissions(+${applyResult.summary.permissions.created}/~${applyResult.summary.permissions.updated}/-${applyResult.summary.permissions.archived}), policies(+${applyResult.summary.policies.created}/~${applyResult.summary.policies.updated}/-${applyResult.summary.policies.archived})`
+    );
+    if (applyResult.stateSignature) {
+      writeLine(`State signature: ${applyResult.stateSignature}`);
+    }
+    return 0;
+  } catch (error) {
+    writeError(formatCommandError(error));
+    return 1;
+  }
+}
+async function promptForConfirmation() {
+  if (!process.stdin.isTTY) {
+    throw new Error(
+      "Non-interactive environment detected. Re-run with --yes to apply without a prompt."
+    );
+  }
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = (await rl.question("Apply these changes? [y/N] ")).trim().toLowerCase();
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+function formatCommandError(error) {
+  if (error instanceof ArbiterError) {
+    return `Error: ${error.message}`;
+  }
+  if (error instanceof Error) {
+    return `Error: ${error.message}`;
+  }
+  return "Error: Unknown failure";
+}
+
+// src/commands/drift.ts
+import { ArbiterError as ArbiterError2 } from "@arbiterhq/sdk";
+
+// src/output/drift.ts
+function renderDriftResult(result) {
+  writeLine(colorize("Arbiter Drift", "bold"));
+  divider();
+  if (!result.drift) {
+    writeLine(colorize("In sync. No drift or adoption suggestions detected.", "green"));
+    return;
+  }
+  const configDrift = result.records.filter(
+    (record) => record.reason === "manifest_create" || record.reason === "manifest_update" || record.reason === "manifest_archive"
+  );
+  const adoptionRecords = result.records.filter(
+    (record) => record.reason === "discovered_unadopted" || record.reason === "pending_review"
+  );
+  if (configDrift.length > 0) {
+    writeLine(colorize("Configuration Drift", "magenta"));
+    for (const record of configDrift) {
+      writeLine(formatDriftRecord(record));
+    }
+    writeLine("");
+  }
+  if (adoptionRecords.length > 0 || result.adoptionSuggestions.length > 0) {
+    writeLine(colorize("Adoption Suggestions", "cyan"));
+    for (const record of adoptionRecords) {
+      writeLine(formatDriftRecord(record));
+    }
+    for (const suggestion of result.adoptionSuggestions) {
+      const id = suggestion.externalId ?? suggestion.action ?? suggestion.id ?? "unknown";
+      writeLine(
+        colorize(
+          `[?] ADOPT ${capitalize2(suggestion.type)} ${id} (discovered runtime asset)`,
+          "cyan"
+        )
+      );
+    }
+  }
+  divider();
+  writeLine(
+    `Drift summary: ${configDrift.length} configuration records, ${adoptionRecords.length + result.adoptionSuggestions.length} adoption suggestions.`
+  );
+}
+function formatDriftRecord(record) {
+  const id = record.externalId ?? record.action ?? record.id ?? "unknown";
+  const label = `${capitalize2(record.type)} ${id}`;
+  const reason = record.reason.replace(/_/g, " ");
+  return colorize(`[!] ${label} \u2014 ${reason}`, "yellow");
+}
+function capitalize2(value) {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+// src/commands/drift.ts
+async function runDrift() {
+  try {
+    const arbiter = createArbiterClient();
+    const result = await arbiter.getDrift();
+    renderDriftResult(result);
+    if (result.drift) {
+      return 2;
+    }
+    return 0;
+  } catch (error) {
+    writeError(formatCommandError2(error));
+    return 1;
+  }
+}
+function formatCommandError2(error) {
+  if (error instanceof ArbiterError2) {
+    return `Error: ${error.message}`;
+  }
+  if (error instanceof Error) {
+    return `Error: ${error.message}`;
+  }
+  return "Error: Unknown failure";
+}
+
+// src/commands/init.ts
+import fs3 from "fs";
+import path4 from "path";
+async function runInit(options) {
+  const manifestPath = resolveManifestPath(options.manifest);
+  if (fs3.existsSync(manifestPath) && !options.force) {
+    throw new Error(
+      `${manifestPath} already exists. Use --force to overwrite.`
+    );
+  }
+  let content;
+  if (options.fromRemote) {
+    const session = resolveSession();
+    const arbiter = createArbiterClient();
+    const drift = await arbiter.getDrift();
+    const workspace = buildWorkspaceFromDrift(drift.adoptionSuggestions, drift.records);
+    content = workspaceToManifestDocument(workspace, {
+      name: session.workspace ?? "imported-workspace",
+      environment: session.environment ?? "production"
+    });
+    writeLine(colorize("Imported adoption suggestions from remote workspace.", "cyan"));
+  } else {
+    content = starterManifestTemplate();
+  }
+  fs3.writeFileSync(manifestPath, `${content}
+`, "utf8");
+  writeLine(colorize("Created manifest template.", "green"));
+  writeLine(`Path: ${path4.resolve(manifestPath)}`);
+  writeLine("Next: arbiter validate \u2192 arbiter plan \u2192 arbiter apply --yes");
+}
+function buildWorkspaceFromDrift(suggestions, records) {
+  const workspace = {
+    agents: [],
+    permissions: [],
+    policies: []
+  };
+  const seenAgents = /* @__PURE__ */ new Set();
+  const seenPermissions = /* @__PURE__ */ new Set();
+  const seenPolicies = /* @__PURE__ */ new Set();
+  for (const suggestion of suggestions) {
+    if (suggestion.type === "agent" && suggestion.externalId && !seenAgents.has(suggestion.externalId)) {
+      workspace.agents.push({
+        externalId: suggestion.externalId,
+        name: suggestion.externalId
+      });
+      seenAgents.add(suggestion.externalId);
+    }
+    if (suggestion.type === "permission" && suggestion.action && !seenPermissions.has(suggestion.action)) {
+      workspace.permissions.push({
+        action: suggestion.action,
+        status: "pending_review"
+      });
+      seenPermissions.add(suggestion.action);
+    }
+    if (suggestion.type === "policy" && suggestion.id && !seenPolicies.has(suggestion.id)) {
+      workspace.policies.push({
+        id: suggestion.id,
+        action: "discovered_action",
+        field: "amount",
+        operator: ">",
+        value: 0,
+        decision: "hold"
+      });
+      seenPolicies.add(suggestion.id);
+    }
+  }
+  for (const record of records) {
+    if (record.type === "agent" && record.externalId && !seenAgents.has(record.externalId)) {
+      workspace.agents.push({
+        externalId: record.externalId,
+        name: record.externalId
+      });
+      seenAgents.add(record.externalId);
+    }
+    if (record.type === "permission" && record.action && !seenPermissions.has(record.action)) {
+      workspace.permissions.push({
+        action: record.action,
+        status: "pending_review"
+      });
+      seenPermissions.add(record.action);
+    }
+    if (record.type === "policy" && record.id && !seenPolicies.has(record.id)) {
+      workspace.policies.push({
+        id: record.id,
+        action: "discovered_action",
+        field: "amount",
+        operator: ">",
+        value: 0,
+        decision: "hold"
+      });
+      seenPolicies.add(record.id);
+    }
+  }
+  return workspace;
+}
+
+// src/commands/login.ts
+import readline2 from "readline/promises";
+import { stdin as input2, stdout as output2 } from "process";
+async function runLogin(options) {
+  const rl = readline2.createInterface({ input: input2, output: output2 });
+  try {
+    const apiKey = options.apiKey ?? (await rl.question("API key: ")).trim();
+    if (apiKey.length === 0) {
+      throw new Error("API key is required");
+    }
+    const workspace = options.workspace ?? (await rl.question("Workspace name (optional): ")).trim();
+    const environment = options.environment ?? (await rl.question("Environment (optional): ")).trim();
+    const baseUrlInput = options.baseUrl ?? (await rl.question(`Endpoint [${DEFAULT_BASE_URL}]: `)).trim();
+    const baseUrl = baseUrlInput.length > 0 ? baseUrlInput : DEFAULT_BASE_URL;
+    const existing = loadCredentialsFile();
+    const credentials = {
+      apiKey,
+      baseUrl
+    };
+    const resolvedWorkspace = workspace.length > 0 ? workspace : existing?.workspace;
+    const resolvedEnvironment = environment.length > 0 ? environment : existing?.environment;
+    if (resolvedWorkspace !== void 0) {
+      credentials.workspace = resolvedWorkspace;
+    }
+    if (resolvedEnvironment !== void 0) {
+      credentials.environment = resolvedEnvironment;
+    }
+    saveCredentialsFile(credentials);
+    writeLine(colorize("Credentials saved.", "green"));
+    writeLine(`Path: ${credentialsFilePath()}`);
+    writeLine("Validation occurs on the next command that contacts the API.");
+  } finally {
+    rl.close();
+  }
+}
+
+// src/commands/plan.ts
+import { ArbiterError as ArbiterError3 } from "@arbiterhq/sdk";
+async function runPlan(options) {
+  try {
+    const manifestPath = resolveManifestPath(options.manifest);
+    const loaded = loadManifestFile(manifestPath);
+    const arbiter = createArbiterClient();
+    const result = await arbiter.plan(loaded.workspace);
+    renderPlanResult(result, {
+      verbose: options.verbose === true,
+      manifestPath
+    });
+    if (planHasActionableChanges(result)) {
+      return 2;
+    }
+    return 0;
+  } catch (error) {
+    writeError(formatCommandError3(error));
+    return 1;
+  }
+}
+function formatCommandError3(error) {
+  if (error instanceof ArbiterError3) {
+    return `Error: ${error.message}`;
+  }
+  if (error instanceof Error) {
+    return `Error: ${error.message}`;
+  }
+  return "Error: Unknown failure";
+}
+
+// src/commands/status.ts
+import { ArbiterError as ArbiterError4 } from "@arbiterhq/sdk";
+async function runStatus(options) {
+  try {
+    const session = resolveSession();
+    const manifestPath = resolveManifestPath(options.manifest);
+    let apiVersion = "n/a";
+    let manifestName = "n/a";
+    try {
+      const loaded = loadManifestFile(manifestPath);
+      apiVersion = loaded.apiVersion ?? "n/a";
+      manifestName = loaded.metadataName ?? manifestPath;
+    } catch {
+      manifestName = `${manifestPath} (missing)`;
+    }
+    const arbiter = createArbiterClient();
+    const signature = await arbiter.getStateSignature();
+    writeLine(colorize("Arbiter Status", "bold"));
+    divider();
+    writeLine(`Endpoint:          ${session.baseUrl}`);
+    writeLine(`Manifest:          ${manifestName}`);
+    writeLine(`Manifest version:  ${apiVersion}`);
+    writeLine(`State signature:   ${signature.stateSignature}`);
+    writeLine(`Workspace label:   ${session.workspace ?? "not set"}`);
+    writeLine(`Environment:       ${session.environment ?? "not set"}`);
+    return 0;
+  } catch (error) {
+    writeError(formatCommandError4(error));
+    return 1;
+  }
+}
+function formatCommandError4(error) {
+  if (error instanceof ArbiterError4) {
+    return `Error: ${error.message}`;
+  }
+  if (error instanceof Error) {
+    return `Error: ${error.message}`;
+  }
+  return "Error: Unknown failure";
+}
+
+// src/commands/validate.ts
+function runValidate(options) {
+  const manifestPath = resolveManifestPath(options.manifest);
+  const issues = validateManifestFile(manifestPath);
+  if (issues.length > 0) {
+    writeError(colorize("Manifest validation failed:", "red"));
+    for (const issue of issues) {
+      const line = issue.line !== null ? ` (line ${issue.line})` : "";
+      writeError(`  ${issue.path}${line}: ${issue.message}`);
+    }
+    return 1;
+  }
+  writeLine(colorize(`\u2713 ${manifestPath} is structurally valid`, "green"));
+  return 0;
+}
+
+// src/commands/whoami.ts
+function runWhoami() {
+  try {
+    const session = resolveSession();
+    const file = loadCredentialsFile();
+    const hasEnvKey = process.env.ARBITER_API_KEY !== void 0;
+    writeLine(colorize("Arbiter Session", "bold"));
+    divider();
+    writeLine(`Workspace:     ${session.workspace ?? "not set"}`);
+    writeLine(`Environment:   ${session.environment ?? "not set"}`);
+    writeLine(`Endpoint:      ${session.baseUrl}`);
+    writeLine(`Authenticated: true`);
+    writeLine(`Credential:    ${credentialsFilePath()}`);
+    writeLine(`API key:       ${maskApiKey(session.apiKey)} (${session.source})`);
+    if (hasEnvKey) {
+      writeLine("Note:          ARBITER_API_KEY overrides stored credentials");
+    }
+    if (!file && hasEnvKey) {
+      writeLine("Note:          Using environment variable only");
+    }
+    return 0;
+  } catch {
+    writeLine(colorize("Authenticated: false", "red"));
+    writeLine("Run `arbiter login` or set ARBITER_API_KEY.");
+    return 1;
+  }
+}
+
+// src/cli.ts
+function buildCli() {
+  const program2 = new Command();
+  program2.name("arbiter").description("Arbiter governance control plane CLI").version("0.1.0");
+  program2.command("login").description("Store API credentials locally (no network validation)").option("--api-key <key>", "API key value").option("--workspace <name>", "Workspace label").option("--environment <name>", "Environment label").option("--base-url <url>", "API base URL").action(async (options) => {
+    await runLogin({
+      ...options.apiKey !== void 0 ? { apiKey: options.apiKey } : {},
+      ...options.workspace !== void 0 ? { workspace: options.workspace } : {},
+      ...options.environment !== void 0 ? { environment: options.environment } : {},
+      ...options.baseUrl !== void 0 ? { baseUrl: options.baseUrl } : {}
+    });
+  });
+  program2.command("init").description("Create a starter arbiter.yaml manifest").option("-m, --manifest <path>", "Manifest file path", "arbiter.yaml").option("--from-remote", "Import adoption suggestions from the remote workspace").option("--force", "Overwrite an existing manifest file").action(async (options) => {
+    await runInit({
+      ...options.manifest !== void 0 ? { manifest: options.manifest } : {},
+      ...options.fromRemote !== void 0 ? { fromRemote: options.fromRemote } : {},
+      ...options.force !== void 0 ? { force: options.force } : {}
+    });
+  });
+  program2.command("validate").description("Validate local arbiter.yaml structure (no network calls)").option("-m, --manifest <path>", "Manifest file path", "arbiter.yaml").action((options) => {
+    const code = runValidate({
+      ...options.manifest !== void 0 ? { manifest: options.manifest } : {}
+    });
+    process.exit(code);
+  });
+  program2.command("plan").description("Show manifest diff against the remote workspace").option("-m, --manifest <path>", "Manifest file path", "arbiter.yaml").option("--verbose", "Include unchanged resource summary").action(async (options) => {
+    const code = await runPlan({
+      ...options.manifest !== void 0 ? { manifest: options.manifest } : {},
+      ...options.verbose !== void 0 ? { verbose: options.verbose } : {}
+    });
+    process.exit(code);
+  });
+  program2.command("apply").description("Apply manifest changes to the remote workspace").option("-m, --manifest <path>", "Manifest file path", "arbiter.yaml").option("--yes", "Skip confirmation prompt (required for CI/CD)").option("--verbose", "Include unchanged resource summary in plan preview").action(async (options) => {
+    const code = await runApply({
+      ...options.manifest !== void 0 ? { manifest: options.manifest } : {},
+      ...options.yes !== void 0 ? { yes: options.yes } : {},
+      ...options.verbose !== void 0 ? { verbose: options.verbose } : {}
+    });
+    process.exit(code);
+  });
+  program2.command("drift").description("Show workspace drift and adoption suggestions").action(async () => {
+    const code = await runDrift();
+    process.exit(code);
+  });
+  program2.command("status").description("Show endpoint, manifest version, and state signature").option("-m, --manifest <path>", "Manifest file path", "arbiter.yaml").action(async (options) => {
+    const code = await runStatus({
+      ...options.manifest !== void 0 ? { manifest: options.manifest } : {}
+    });
+    process.exit(code);
+  });
+  program2.command("whoami").description("Show active credential session context").action(() => {
+    const code = runWhoami();
+    process.exit(code);
+  });
+  return program2;
+}
+
+// src/index.ts
+var program = buildCli();
+program.parseAsync(process.argv).catch((error) => {
+  const message = error instanceof Error ? error.message : "Unknown CLI failure";
+  process.stderr.write(`Error: ${message}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@arbiterhq/cli",
+  "version": "0.1.0",
+  "description": "Official Arbiter command line interface",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "arbiter": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@arbiterhq/sdk": "^0.2.0",
+    "commander": "^13.1.0",
+    "yaml": "^2.8.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3"
+  },
+  "keywords": [
+    "arbiter",
+    "cli",
+    "governance"
+  ],
+  "homepage": "https://github.com/sumitbirru1-halo/arbiter-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/sumitbirru1-halo/arbiter-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sumitbirru1-halo/arbiter-sdk.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}