@flamecast/cli 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# flamecast
+
+Command-line client for [Flamecast](https://flamecast.dev). Manage cloud agents and sessions from your terminal.
+
+## Install
+
+```bash
+git clone https://github.com/smithery-ai/flamecast-cli
+cd flamecast-cli
+bun install
+bun run build       # compiles dist/flamecast
+```
+
+Requires [Bun](https://bun.sh) for source builds. The compiled binary runs standalone.
+
+## Quickstart
+
+```bash
+flamecast login     # browser sign-in, stores an API key locally
+flamecast whoami
+flamecast agents
+flamecast sessions
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `flamecast login` | Sign in via the browser. Stores an API key. |
+| `flamecast logout` | Clear the local API key. |
+| `flamecast whoami` | Print the currently authed identity. |
+| `flamecast config` | Show config file path + base URL. |
+| `flamecast agents` | List agents in your workspace. |
+| `flamecast sessions` | List recent sessions. |
+| `flamecast sessions create --input <text>` | Launch a Think session. |
+| `flamecast sessions get <sessionId>` | Show one session. |
+| `flamecast sessions events <sessionId>` | Dump the event log. |
+
+### Launching a session
+
+```bash
+flamecast sessions create --input "summarize my open Linear tickets"
+```
+
+By default this runs on Flamecast's free tier: the server fills in
+`runtime.auth` from its own AI Gateway key. The free tier currently allows
+`anthropic/claude-haiku-4-5` only, with a monthly cap per org (10 sessions
+and $5 of gateway spend). Set `AI_GATEWAY_API_KEY` to bring your own key
+and bypass the cap.
+
+Flags on `sessions create`:
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--input <text>` | _(required)_ | First message to the agent. |
+| `--model <id>` | `anthropic/claude-haiku-4-5` | Free tier supports this model only; BYOK keys can use any Think-supported model. |
+| `--agent-id <id>` | _none_ | Launch a saved agent instead of an inline runtime. |
+| `--async` | off | Return immediately; poll `sessions get` / `sessions events` for progress. |
+
+## Configuration
+
+Credentials live at `~/.config/flamecast/config.json` (respects `$XDG_CONFIG_HOME`). Delete the file or run `flamecast logout` to clear.
+
+| Env var | Default | Notes |
+|---|---|---|
+| `FLAMECAST_URL` | `https://flamecast.dev` | Point at a different worker. |
+| `AI_GATEWAY_API_KEY` | _none_ | Optional. When set, `sessions create` uses BYOK and bypasses the free-tier cap. |
+
+## Development
+
+```bash
+bun run bin/flamecast.ts <command>     # run from source
+bun run typecheck                       # type-check
+```

package/bin/flamecast.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+import { dispatch } from "../src/commands.ts"
+
+const code = await dispatch(process.argv.slice(2))
+process.exit(code)

package/package.json

@@ -0,0 +1,30 @@
+{
+	"name": "@flamecast/cli",
+	"version": "0.1.0",
+	"description": "Command-line client for Flamecast. Drives the device-auth flow and wraps the public REST API.",
+	"type": "module",
+	"license": "MIT",
+	"bin": {
+		"flamecast": "./bin/flamecast.ts"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"bin",
+		"src",
+		"README.md"
+	],
+	"scripts": {
+		"dev": "bun run bin/flamecast.ts",
+		"build": "bun build bin/flamecast.ts --compile --outfile dist/flamecast",
+		"typecheck": "bun --bun tsc --noEmit"
+	},
+	"engines": {
+		"bun": ">=1.1"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"typescript": "^5.5.0"
+	}
+}

package/src/auth.ts

@@ -0,0 +1,89 @@
+/**
+ * Device-flow login. Mirrors the Smithery CLI handshake:
+ *   POST /api/auth/cli/session     → { sessionId, authUrl }
+ *   GET  /api/auth/cli/poll/:id    → pending | success(apiKey, organization)
+ *
+ * Bun's built-in fetch + a 2s poll loop. No external deps.
+ */
+import { configBaseUrl, writeConfig, type FlamecastConfig } from "./config.ts"
+
+const POLL_INTERVAL_MS = 2000
+const TIMEOUT_MS = 5 * 60 * 1000
+
+interface SessionResponse {
+	sessionId: string
+	authUrl: string
+}
+
+type PollResponse =
+	| { status: "pending" }
+	| { status: "success"; apiKey: string; organization?: { id: string } }
+	| { status: "error"; message: string }
+
+async function createSession(baseUrl: string): Promise<SessionResponse> {
+	const r = await fetch(`${baseUrl}/api/auth/cli/session`, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({}),
+	})
+	if (!r.ok) throw new Error(`session create: ${r.status} ${r.statusText}`)
+	return (await r.json()) as SessionResponse
+}
+
+async function poll(baseUrl: string, sessionId: string): Promise<PollResponse> {
+	const r = await fetch(`${baseUrl}/api/auth/cli/poll/${sessionId}`)
+	if (r.status === 404) {
+		return { status: "error", message: "session expired" }
+	}
+	if (!r.ok) {
+		return { status: "error", message: `poll: ${r.status} ${r.statusText}` }
+	}
+	return (await r.json()) as PollResponse
+}
+
+async function openBrowser(url: string): Promise<void> {
+	const platform = process.platform
+	const cmd =
+		platform === "darwin" ? ["open", url] :
+		platform === "win32" ? ["cmd", "/c", "start", "", url] :
+		["xdg-open", url]
+	try {
+		const proc = Bun.spawn(cmd, { stdout: "ignore", stderr: "ignore" })
+		await proc.exited
+	} catch {
+		// Browser open is best-effort; URL is already printed.
+	}
+}
+
+export async function login(): Promise<FlamecastConfig> {
+	const baseUrl = configBaseUrl()
+	process.stderr.write("Preparing authentication…\n")
+	const session = await createSession(baseUrl)
+	process.stderr.write("\nSign in to authorize the Flamecast CLI:\n")
+	process.stderr.write(`  ${session.authUrl}\n\n`)
+	await openBrowser(session.authUrl)
+
+	const deadline = Date.now() + TIMEOUT_MS
+	let dots = 0
+	while (Date.now() < deadline) {
+		const result = await poll(baseUrl, session.sessionId)
+		if (result.status === "success") {
+			process.stderr.write("\nAuthorized.\n")
+			const config: FlamecastConfig = {
+				baseUrl,
+				apiKey: result.apiKey,
+				organization: result.organization,
+				updatedAt: new Date().toISOString(),
+			}
+			await writeConfig(config)
+			return config
+		}
+		if (result.status === "error") {
+			throw new Error(`Authentication failed: ${result.message}`)
+		}
+		dots = (dots + 1) % 4
+		process.stderr.write(`\rWaiting for authorization${".".repeat(dots).padEnd(3)}`)
+		await Bun.sleep(POLL_INTERVAL_MS)
+	}
+	throw new Error("Authentication timed out after 5 minutes. Re-run `flamecast login`.")
+}

package/src/commands.ts

@@ -0,0 +1,97 @@
+import { login } from "./auth.ts"
+import { clearConfig, configBaseUrl, configPath, readConfig } from "./config.ts"
+import { sessions } from "./sessions.ts"
+import { whoami } from "./whoami.ts"
+
+const USAGE = `flamecast — programmable cloud agents
+
+Usage:
+  flamecast login                          Sign in via your browser, store an API key
+  flamecast logout                         Clear the local API key
+  flamecast whoami                         Print the currently authed identity
+  flamecast config                         Show the local config file path + base URL
+  flamecast agents                         List agents in your workspace
+  flamecast sessions                       List recent sessions
+  flamecast sessions create --input <text> Launch a Think session
+  flamecast sessions get <sessionId>       Show one session
+  flamecast sessions events <sessionId>    Dump the event log
+
+Environment:
+  FLAMECAST_URL         Override the API base URL (default: https://flamecast.dev)
+  AI_GATEWAY_API_KEY    Optional. BYOK key to bypass the free-tier cap
+`
+
+async function requireAuth() {
+	const config = await readConfig()
+	if (!config?.apiKey) {
+		process.stderr.write("Not signed in. Run `flamecast login` first.\n")
+		process.exit(1)
+	}
+	return config
+}
+
+export async function dispatch(argv: string[]): Promise<number> {
+	const cmd = argv[0]
+	switch (cmd) {
+		case undefined:
+		case "help":
+		case "--help":
+		case "-h":
+			process.stdout.write(USAGE)
+			return 0
+
+		case "login": {
+			await login()
+			return 0
+		}
+
+		case "logout": {
+			const removed = await clearConfig()
+			process.stderr.write(
+				removed ? "Signed out.\n" : "No active session.\n",
+			)
+			return removed ? 0 : 1
+		}
+
+		case "whoami": {
+			const me = await whoami()
+			if (!me.authed) {
+				process.stderr.write("Not signed in.\n")
+				return 1
+			}
+			process.stdout.write(`${me.email ?? me.name ?? me.workosUserId}\n`)
+			if (me.orgId) process.stdout.write(`org: ${me.orgId}\n`)
+			return 0
+		}
+
+		case "config": {
+			process.stdout.write(`baseUrl: ${configBaseUrl()}\n`)
+			process.stdout.write(`config:  ${configPath()}\n`)
+			const config = await readConfig()
+			process.stdout.write(`status:  ${config?.apiKey ? "signed in" : "signed out"}\n`)
+			return 0
+		}
+
+		case "agents": {
+			const config = await requireAuth()
+			const r = await fetch(`${config.baseUrl}/agents`, {
+				headers: { authorization: `Bearer ${config.apiKey}` },
+			})
+			if (!r.ok) {
+				process.stderr.write(`list agents: ${r.status} ${r.statusText}\n`)
+				return 1
+			}
+			process.stdout.write(`${JSON.stringify(await r.json(), null, 2)}\n`)
+			return 0
+		}
+
+		case "sessions": {
+			return sessions(argv.slice(1))
+		}
+
+		default: {
+			process.stderr.write(`Unknown command: ${cmd}\n\n${USAGE}`)
+			return 2
+		}
+	}
+}

package/src/config.ts

@@ -0,0 +1,55 @@
+/**
+ * Local credential store. Plain JSON at $XDG_CONFIG_HOME/flamecast/config.json
+ * (falling back to ~/.config/flamecast/config.json). Same shape Stripe and
+ * gh use — a single file with the active profile, easy to inspect and rm.
+ */
+import { mkdir } from "node:fs/promises"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+
+export interface FlamecastConfig {
+	baseUrl: string
+	apiKey?: string
+	organization?: { id: string }
+	updatedAt: string
+}
+
+const DEFAULT_BASE_URL = "https://flamecast.dev"
+
+export function configBaseUrl(): string {
+	return process.env.FLAMECAST_URL ?? DEFAULT_BASE_URL
+}
+
+export function configPath(): string {
+	const xdg = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config")
+	return join(xdg, "flamecast", "config.json")
+}
+
+export async function readConfig(): Promise<FlamecastConfig | null> {
+	const path = configPath()
+	const file = Bun.file(path)
+	if (!(await file.exists())) return null
+	try {
+		return (await file.json()) as FlamecastConfig
+	} catch {
+		return null
+	}
+}
+
+export async function writeConfig(config: FlamecastConfig): Promise<void> {
+	const path = configPath()
+	await mkdir(dirname(path), { recursive: true })
+	await Bun.write(path, `${JSON.stringify(config, null, 2)}\n`)
+}
+
+export async function clearConfig(): Promise<boolean> {
+	const path = configPath()
+	const file = Bun.file(path)
+	if (!(await file.exists())) return false
+	await Bun.write(path, "")
+	// Bun.write with empty string truncates but leaves the file. Remove
+	// fully so a stale empty config can't confuse readConfig.
+	const fs = await import("node:fs/promises")
+	await fs.unlink(path).catch(() => undefined)
+	return true
+}

package/src/sessions.ts

@@ -0,0 +1,179 @@
+/**
+ * `flamecast sessions` subcommands: list, create, get, events.
+ */
+import { readConfig } from "./config.ts"
+
+interface ParsedFlags {
+	positional: string[]
+	flags: Record<string, string | boolean>
+}
+
+function parseFlags(argv: string[]): ParsedFlags {
+	const positional: string[] = []
+	const flags: Record<string, string | boolean> = {}
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i]
+		if (a.startsWith("--")) {
+			const key = a.slice(2)
+			const next = argv[i + 1]
+			if (next && !next.startsWith("--")) {
+				flags[key] = next
+				i++
+			} else {
+				flags[key] = true
+			}
+		} else {
+			positional.push(a)
+		}
+	}
+	return { positional, flags }
+}
+
+async function authed() {
+	const config = await readConfig()
+	if (!config?.apiKey) {
+		process.stderr.write("Not signed in. Run `flamecast login` first.\n")
+		process.exit(1)
+	}
+	return config
+}
+
+function printJson(data: unknown) {
+	process.stdout.write(`${JSON.stringify(data, null, 2)}\n`)
+}
+
+async function list(): Promise<number> {
+	const config = await authed()
+	const r = await fetch(`${config.baseUrl}/sessions`, {
+		headers: { authorization: `Bearer ${config.apiKey}` },
+	})
+	if (!r.ok) {
+		process.stderr.write(`list sessions: ${r.status} ${r.statusText}\n`)
+		return 1
+	}
+	printJson(await r.json())
+	return 0
+}
+
+async function get(id: string | undefined): Promise<number> {
+	if (!id) {
+		process.stderr.write("usage: flamecast sessions get <sessionId>\n")
+		return 2
+	}
+	const config = await authed()
+	const r = await fetch(`${config.baseUrl}/sessions/${id}`, {
+		headers: { authorization: `Bearer ${config.apiKey}` },
+	})
+	if (r.status === 404) {
+		process.stderr.write("session not found\n")
+		return 1
+	}
+	if (!r.ok) {
+		process.stderr.write(`get session: ${r.status} ${r.statusText}\n`)
+		return 1
+	}
+	printJson(await r.json())
+	return 0
+}
+
+async function events(id: string | undefined): Promise<number> {
+	if (!id) {
+		process.stderr.write("usage: flamecast sessions events <sessionId>\n")
+		return 2
+	}
+	const config = await authed()
+	const r = await fetch(
+		`${config.baseUrl}/sessions/${id}/events?limit=500`,
+		{ headers: { authorization: `Bearer ${config.apiKey}` } },
+	)
+	if (!r.ok) {
+		process.stderr.write(`events: ${r.status} ${r.statusText}\n`)
+		return 1
+	}
+	printJson(await r.json())
+	return 0
+}
+
+async function create(flags: Record<string, string | boolean>): Promise<number> {
+	const input = typeof flags.input === "string" ? flags.input : undefined
+	if (!input) {
+		process.stderr.write(
+			"usage: flamecast sessions create --input <text> [--model <id>] [--agent-id <id>] [--async]\n",
+		)
+		return 2
+	}
+	const model = typeof flags.model === "string" ? flags.model : "anthropic/claude-haiku-4-5"
+	const agentId = typeof flags["agent-id"] === "string" ? flags["agent-id"] : undefined
+	const asyncFlag = flags.async === true || flags.async === "true"
+	const gatewayKey = process.env.AI_GATEWAY_API_KEY
+	const config = await authed()
+
+	const body: Record<string, unknown> = { input, async: asyncFlag }
+	if (agentId) {
+		body.agentId = agentId
+	} else {
+		// runtime.auth is optional: the server fills it from its free-tier key
+		// (subject to monthly caps) when omitted and the model is on the free
+		// allowlist. Pass AI_GATEWAY_API_KEY to bypass the cap with BYOK.
+		const runtime: Record<string, unknown> = {
+			id: "think",
+			config: { model, toolMode: "mcp" },
+		}
+		if (gatewayKey) {
+			runtime.auth = { type: "api_key", key: gatewayKey }
+		}
+		body.agent = { runtime }
+	}
+
+	const r = await fetch(`${config.baseUrl}/sessions`, {
+		method: "POST",
+		headers: {
+			authorization: `Bearer ${config.apiKey}`,
+			"content-type": "application/json",
+		},
+		body: JSON.stringify(body),
+	})
+	if (!r.ok) {
+		const text = await r.text().catch(() => r.statusText)
+		process.stderr.write(`create session: ${r.status} ${text}\n`)
+		return 1
+	}
+	printJson(await r.json())
+	return 0
+}
+
+const SESSIONS_USAGE = `flamecast sessions <verb>
+
+Verbs:
+  list                                List recent sessions
+  create --input <text> [--model M]   Launch a Think session
+         [--agent-id ID] [--async]
+  get <sessionId>                     Show one session
+  events <sessionId>                  Dump the event log
+
+Env:
+  AI_GATEWAY_API_KEY    Optional. BYOK key to bypass the free-tier cap.
+`
+
+export async function sessions(argv: string[]): Promise<number> {
+	const { positional, flags } = parseFlags(argv)
+	const verb = positional[0] ?? "list"
+	switch (verb) {
+		case "list":
+			return list()
+		case "create":
+			return create(flags)
+		case "get":
+			return get(positional[1])
+		case "events":
+			return events(positional[1])
+		case "help":
+		case "--help":
+		case "-h":
+			process.stdout.write(SESSIONS_USAGE)
+			return 0
+		default:
+			process.stderr.write(`Unknown sessions verb: ${verb}\n\n${SESSIONS_USAGE}`)
+			return 2
+	}
+}

package/src/whoami.ts

@@ -0,0 +1,23 @@
+/**
+ * Calls /auth/me on the configured base URL using the stored API key.
+ * Used by `flamecast whoami` and as a probe before mutating commands.
+ */
+import { readConfig } from "./config.ts"
+
+export interface WhoamiResult {
+	authed: boolean
+	email?: string | null
+	name?: string | null
+	workosUserId?: string
+	orgId?: string
+}
+
+export async function whoami(): Promise<WhoamiResult> {
+	const config = await readConfig()
+	if (!config?.apiKey) return { authed: false }
+	const r = await fetch(`${config.baseUrl}/auth/me`, {
+		headers: { authorization: `Bearer ${config.apiKey}` },
+	})
+	if (!r.ok) return { authed: false }
+	return (await r.json()) as WhoamiResult
+}