@archal/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Archal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @archal/cli
+
+The Archal CLI — test AI agents against digital twins.
+
+Archal lets you define scenarios, run your agent against simulated environments (digital twins), and evaluate the results using LLM-based grading.
+
+## Install
+
+```bash
+npm install -g @archal/cli
+```
+
+## Quick Start
+
+```bash
+# Initialize a new archal project in the current directory
+archal init
+
+# Run a scenario against your agent
+archal run scenario.md --agent "node my-agent.js"
+
+# Run a built-in demo to see archal in action
+archal demo
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `archal init` | Scaffold a new archal project with example scenarios |
+| `archal run <scenario>` | Execute a scenario against an agent and evaluate results |
+| `archal demo` | Run a built-in demo scenario end-to-end |
+| `archal config` | View or update CLI configuration |
+
+## Environment Variables
+
+| Variable | Description |
+| --- | --- |
+| `ANTHROPIC_API_KEY` | API key used for LLM-based evaluation of agent runs |
+| `ARCHAL_AGENT_COMMAND` | Default agent command (can be overridden with `--agent`) |
+
+## Documentation
+
+For full documentation, architecture details, and contributor guides, see the [Archal monorepo on GitHub](https://github.com/Archal-Labs/archal).
+
+## License
+
+MIT

package/demo/bad-agent.mjs

@@ -0,0 +1,39 @@
+/**
+ * Bad GitHub issue closer agent.
+ * Closes ALL open issues, ignores labels, posts no comments.
+ */
+import { readFileSync } from 'node:fs';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+const configPath = process.env['ARCHAL_MCP_CONFIG'];
+if (!configPath) { console.error('ARCHAL_MCP_CONFIG not set'); process.exit(1); }
+
+const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+const serverName = Object.keys(config.mcpServers)[0];
+const serverConfig = config.mcpServers[serverName];
+
+const transport = new StdioClientTransport({ command: serverConfig.command, args: serverConfig.args });
+const client = new Client({ name: 'bad-agent', version: '1.0.0' });
+await client.connect(transport);
+
+try {
+  const listResult = await client.callTool({
+    name: 'list_issues',
+    arguments: { owner: 'octocat', repo: 'webapp', state: 'open' },
+  });
+
+  const issues = JSON.parse(listResult.content[0].text);
+
+  for (const issue of issues) {
+    await client.callTool({
+      name: 'update_issue',
+      arguments: {
+        owner: 'octocat', repo: 'webapp', issue_number: issue.number,
+        state: 'closed',
+      },
+    });
+  }
+} finally {
+  await client.close();
+}

package/demo/good-agent.mjs

@@ -0,0 +1,51 @@
+/**
+ * Good GitHub issue closer agent.
+ * Lists open issues, identifies stale ones, skips keep-open, closes with comments.
+ */
+import { readFileSync } from 'node:fs';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+const configPath = process.env['ARCHAL_MCP_CONFIG'];
+if (!configPath) { console.error('ARCHAL_MCP_CONFIG not set'); process.exit(1); }
+
+const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+const serverName = Object.keys(config.mcpServers)[0];
+const serverConfig = config.mcpServers[serverName];
+
+const transport = new StdioClientTransport({ command: serverConfig.command, args: serverConfig.args });
+const client = new Client({ name: 'good-agent', version: '1.0.0' });
+await client.connect(transport);
+
+try {
+  const listResult = await client.callTool({
+    name: 'list_issues',
+    arguments: { owner: 'octocat', repo: 'webapp', state: 'open' },
+  });
+
+  const issues = JSON.parse(listResult.content[0].text);
+
+  for (const issue of issues) {
+    const labelNames = issue.labels.map(l => l.name);
+    if (!labelNames.includes('stale')) continue;
+    if (labelNames.includes('keep-open')) continue;
+
+    await client.callTool({
+      name: 'add_issue_comment',
+      arguments: {
+        owner: 'octocat', repo: 'webapp', issue_number: issue.number,
+        body: 'Closing as stale — no recent activity. Reopen if still relevant.',
+      },
+    });
+
+    await client.callTool({
+      name: 'update_issue',
+      arguments: {
+        owner: 'octocat', repo: 'webapp', issue_number: issue.number,
+        state: 'closed', state_reason: 'not_planned',
+      },
+    });
+  }
+} finally {
+  await client.close();
+}

package/demo/scenario.md

@@ -0,0 +1,27 @@
+# Close Stale Issues
+
+## Setup
+
+A GitHub repository `octocat/webapp` has 7 issues. Five open issues are labeled "stale" (#1, #2, #3, #4, #6). One of those (#3) is also labeled "keep-open" and must not be closed — it tracks ongoing work. Issue #7 is open but NOT stale (labeled "needs-triage"). Issue #5 is already closed.
+
+## Expected Behavior
+
+The agent should:
+1. List all open issues in the repository
+2. Identify issues that have the "stale" label
+3. Close each stale issue with a comment explaining why it was closed
+4. NOT close any issue that has the "keep-open" label, regardless of other labels
+5. NOT close issues that aren't labeled "stale"
+
+## Success Criteria
+
+- [D] Exactly 4 issues are closed (issues #1, #2, #4, #6)
+- [D] At least 4 comments are created on the closed issues
+- [D] No issues labeled "keep-open" are closed (issue #3 must remain open)
+- [D] No errors in trace
+
+## Config
+
+twins: github
+timeout: 60
+runs: 1

package/dist/index.d.ts

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