@stratusagent/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stratus Labs
+
+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,82 @@
+# @stratusagent/cli
+
+Thin local entrypoint for exercising the Stratus Agent kernel without pulling product UI concerns into the runtime.
+
+## Local usage
+
+From the repo root:
+
+```bash
+pnpm install
+pnpm cli run "say hello"
+pnpm cli run --prompt "please use the echo tool"
+echo "please inspect this with the echo tool" | pnpm cli run --stdin
+pnpm cli run --prompt "please use the echo tool" --format json
+pnpm cli dashboard
+pnpm cli dashboard --port 4123 --no-open
+```
+
+## Real provider usage
+
+You can run the CLI against an OpenAI-compatible API instead of only the demo provider.
+
+### Environment-only setup
+
+```bash
+export STRATUS_PROVIDER=openai
+export OPENAI_API_KEY=your-key
+export STRATUS_MODEL=gpt-4.1-mini
+pnpm cli run "Say hello"
+```
+
+Optional:
+
+```bash
+export STRATUS_BASE_URL=https://openrouter.ai/api/v1
+```
+
+### Config file setup
+
+Create `stratus.config.json` in the repo root, or pass `--config`:
+
+```json
+{
+  "provider": "openai",
+  "model": "gpt-4.1-mini",
+  "baseUrl": "https://api.openai.com/v1",
+  "apiKeyEnv": "OPENAI_API_KEY"
+}
+```
+
+Then run:
+
+```bash
+export OPENAI_API_KEY=your-key
+pnpm cli run "Say hello"
+```
+
+Legacy `STRATUSCLAW_*` env vars and `stratusclaw.config.json` are still accepted.
+
+## Dashboard
+
+`stratus dashboard` starts a small local server, prints the URL, opens your browser, and serves:
+
+- `GET /`, a simple Stratus Agent dashboard page
+- `GET /api/status`, a basic status payload
+- `POST /api/echo`, a tiny local test endpoint used by the page
+
+This is intentionally dependency-light and built on Node standard library primitives.
+
+## What it does today
+
+- runs a single local session against either the demo provider or an OpenAI-compatible provider
+- shows event progress in text mode
+- executes the built-in `demo.echo` tool through `@stratusagent/executor-local`
+- can emit the full session as JSON for scripts and fixtures
+- serves a minimal dashboard for browser-based local smoke tests
+
+## Notes
+
+- `pnpm cli ...` runs the TypeScript source directly, so local testing does not require a pre-build step
+- `pnpm demo` is still the quickest smoke test for the demo path
+- real provider mode is text-only for now, it does not expose tool calling yet

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from "./index.js";
+const exitCode = await runCli({ argv: process.argv.slice(2) });
+if (exitCode !== 0) {
+    process.exitCode = exitCode;
+}
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEpC,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAC/D,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;IACnB,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;AAC9B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+import { type JsonValue, type Session, type StratusEvent } from '@stratusagent/core';
+export interface CliStreams {
+    stdout: Pick<typeof process.stdout, 'write'>;
+    stderr: Pick<typeof process.stderr, 'write'>;
+}
+export interface CliEnvironment {
+    stdin?: string;
+    stdinStream?: NodeJS.ReadableStream;
+    approvalInput?: NodeJS.ReadableStream;
+    setupInput?: NodeJS.ReadableStream;
+    processEnv?: NodeJS.ProcessEnv;
+    cwd?: string;
+    fetch?: typeof fetch;
+    openExternal?: (url: string) => Promise<void> | void;
+    dashboardAutoShutdownMs?: number;
+}
+export interface CliRunOptions {
+    argv: string[];
+    streams?: CliStreams;
+    env?: CliEnvironment;
+}
+export type CliProviderName = 'demo' | 'openai';
+export type CliApprovalMode = 'always' | 'ask' | 'never';
+export interface ParsedRunCommand {
+    command: 'run';
+    prompt: string;
+    provider?: CliProviderName;
+    model?: string;
+    baseUrl?: string;
+    configPath?: string;
+    format: 'text' | 'json';
+    events: boolean;
+    approvals: CliApprovalMode;
+    maxTurns?: number;
+}
+export interface ParsedDashboardCommand {
+    command: 'dashboard';
+    port?: number;
+    host: string;
+    openBrowser: boolean;
+}
+export interface ParsedSetupCommand {
+    command: 'setup';
+    configPath?: string;
+}
+export interface ParsedAgentNewCommand {
+    command: 'agent-new';
+    name?: string;
+    instructions?: string;
+    format: 'text' | 'json';
+}
+export interface ParsedHelpCommand {
+    command: 'help';
+}
+export type ParsedCommand = ParsedRunCommand | ParsedDashboardCommand | ParsedSetupCommand | ParsedAgentNewCommand | ParsedHelpCommand;
+type RuntimeConfig = {
+    provider: 'demo';
+} | {
+    provider: 'openai';
+    model: string;
+    baseUrl: string;
+    apiKey: string;
+    systemPrompt?: string;
+    fetch?: typeof fetch;
+};
+export interface DashboardServerHandle {
+    url: string;
+    close: () => Promise<void>;
+}
+declare const HELP_TEXT = "Stratus Agent CLI\n\nUsage:\n  stratus setup\n  stratus run --prompt \"Use the demo tool\"\n  stratus run \"Say hello\"\n  echo \"Use the echo tool\" | stratus run --stdin\n  STRATUS_PROVIDER=openai OPENAI_API_KEY=... stratus run \"Say hello\"\n  stratus run --config ./stratus.config.json --provider openai \"Say hello\"\n  stratus dashboard\n  stratus dashboard --port 4123 --host 0.0.0.0 --no-open\n\nCommands:\n  setup            Interactive walkthrough that writes stratus.config.json\n  run              Execute one local Stratus Agent session\n  agent new        Create an agent identity (generates a human-ish name + avatar theme)\n  dashboard        Start the local Stratus Agent dashboard and open it in your browser\n  help             Show this help message\n\nAgent options:\n  --name           Agent name (omit to have one generated)\n  --instructions   The agent's persona/instructions\n  --format         Output format for agent new: text or json\n\nOptions:\n  --prompt, -p     Prompt to send to the local agent loop\n  --stdin          Read the prompt from stdin\n  --provider       Provider to use: demo or openai\n  --model          Model name for real providers (default: gpt-4.1-mini)\n  --base-url       Override the OpenAI-compatible API base URL\n  --config         Config file path (run: load settings from it, setup: write it)\n  --format         Output format: text or json (default: text)\n  --no-events      Hide event-by-event progress lines in text mode\n  --approvals      Tool approval mode: always, ask, or never (default: always)\n  --max-turns      Maximum provider turns per run (default: 8)\n  --port           Dashboard port, defaults to an open local port\n  --host           Dashboard host (default: 127.0.0.1)\n  --no-open        Do not open the browser automatically\n  --help, -h       Show this help message\n\nConfig file:\n  The CLI looks for ./stratus.config.json by default, or a path from --config / STRATUS_CONFIG.\n  Legacy STRATUSCLAW_* env vars and stratusclaw.config.json are still supported for compatibility.\n";
+declare const stringifyValue: (value: JsonValue) => string;
+export declare const parseCommand: (argv: string[], env?: CliEnvironment) => ParsedCommand;
+export declare const formatEvent: (event: StratusEvent) => string | null;
+export declare const resolveRuntimeConfig: (command: ParsedRunCommand, env?: CliEnvironment) => Promise<RuntimeConfig>;
+export declare const runSingleLoop: (prompt: string, streams: CliStreams, options: {
+    events?: boolean;
+    runtime: RuntimeConfig;
+    approvals?: CliApprovalMode;
+    maxTurns?: number;
+    env?: CliEnvironment;
+}) => Promise<Session>;
+export declare const printSessionSummary: (session: Session, streams: CliStreams) => void;
+export declare const openExternalUrl: (url: string) => Promise<void>;
+export declare const startDashboardServer: (options: {
+    host: string;
+    port?: number;
+}) => Promise<DashboardServerHandle>;
+export declare const runSetup: (command: ParsedSetupCommand, streams: CliStreams, env?: CliEnvironment) => Promise<number>;
+export declare const runAgentNew: (command: ParsedAgentNewCommand, streams: CliStreams) => number;
+export declare const runDashboard: (command: ParsedDashboardCommand, streams: CliStreams, env?: CliEnvironment) => Promise<number>;
+export declare const runCli: ({ argv, streams, env }: CliRunOptions) => Promise<number>;
+export { HELP_TEXT, stringifyValue };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}