@shogo-ai/worker 1.7.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shogo Technologies, Inc.
+
+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,179 @@
+# @shogo-ai/worker
+
+Run Shogo Cloud Agents on a machine you already own — a laptop, devbox, or CI runner.
+Outbound-only: the worker dials Shogo Cloud over HTTPS, never the other way around.
+
+> Licensed **MIT**. The agent runtime it spawns is licensed AGPL-3.0-or-later
+> and ships as a separate binary — see [Architecture & licensing](#architecture--licensing) below.
+
+## Install
+
+```bash
+# Requires node >= 20 (or bun >= 1.3)
+npm i -g @shogo-ai/worker
+```
+
+> Prefer a single self-contained binary? Grab the prebuilt tarball for your
+> OS / arch from the [latest worker release](https://github.com/shogo-ai/shogo-ai/releases?q=worker-v)
+> — it has no Node / Bun dependency.
+
+## Quick start
+
+```bash
+# 1. Sign in (opens your browser; falls back to --api-key for CI)
+shogo login
+
+# 2. Download the AGPL agent-runtime binary into ~/.shogo/runtime/
+shogo runtime install
+
+# 3. Start the worker (detached by default)
+shogo worker start --name my-devbox
+
+# 4. Confirm it's online
+shogo worker status
+
+# 5. Open https://studio.shogo.ai — your machine appears in the
+#    environment dropdown next to the desktop entries.
+```
+
+### Headless / CI
+
+```bash
+# Skip the browser flow with a personal API key from
+# https://studio.shogo.ai/api-keys
+shogo login --api-key "shogo_sk_..."
+
+# Or skip `login` entirely
+SHOGO_API_KEY=shogo_sk_... shogo runtime install
+SHOGO_API_KEY=shogo_sk_... shogo worker start --foreground
+```
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `shogo login` | Browser device-code flow against `studio.shogo.ai`. `--api-key` / `SHOGO_API_KEY` for headless. `--workspace <id>` to pre-select. `--no-browser` to print the URL only. |
+| `shogo runtime install` | Download + verify + extract the AGPL agent-runtime tarball into `~/.shogo/runtime/`. Flags: `--channel stable\|beta\|nightly`, `--version`, `--force`, `--base-url`. |
+| `shogo runtime version` | Print the installed agent-runtime version. |
+| `shogo runtime where` | Print the resolved binary path (priority order: `--runtime-bin` → `$SHOGO_AGENT_RUNTIME_BIN` → `~/.shogo/runtime/agent-runtime` → `$PATH`). |
+| `shogo runtime update` | Reinstall the latest in-channel build. |
+| `shogo worker start` | Pair this machine with Shogo Cloud. `--foreground` to attach to stdout (e.g. `systemd --user`); default detaches and writes `~/.shogo/worker.pid`. |
+| `shogo worker stop` | Kill the running worker via PID file. |
+| `shogo worker status` | Online / offline + uptime. |
+| `shogo worker logs [-f]` | Tail `~/.shogo/logs/worker.log`. |
+| `shogo config show` | Print config (API key masked). |
+| `shogo config set <key> <value>` | Edit a single key. |
+
+## Files & layout
+
+```
+~/.shogo/
+├── config.json        # API key + cloud URL (mode 0600)
+├── device-id          # stable per-machine UUID; dedupes re-logins
+├── worker.pid         # lifecycle file for `worker start/stop/status`
+├── logs/
+│   ├── worker.log
+│   └── worker.err.log
+└── runtime/
+    ├── agent-runtime  # AGPL binary, downloaded by `shogo runtime install`
+    └── version.json
+```
+
+## Networking
+
+The worker needs outbound HTTPS (TCP 443) to 3 hosts. **No inbound ports required.**
+
+| Host | Purpose | If blocked |
+|------|---------|-----------|
+| `studio.shogo.ai` | Sign-in, session, heartbeat, on-demand tunnel WS | **FATAL** — worker can't run |
+| `api-direct.shogo.ai` | Direct tunnel fallback (when used) | Graceful — edge routing takes over |
+| `github.com` / `objects.githubusercontent.com` | Runtime binary downloads (`shogo runtime install`) | Only `runtime install/update` affected; can be self-mirrored via `--base-url` |
+
+### Corporate proxy
+
+```bash
+# HTTPS_PROXY / https_proxy / HTTP_PROXY / http_proxy all honoured
+HTTPS_PROXY=http://proxy.corp:3128 shogo worker start
+
+# Or pass explicitly (overrides env)
+shogo worker start --proxy http://proxy.corp:3128
+
+# TLS-inspecting proxy needs your corp root CA
+NODE_EXTRA_CA_CERTS=/etc/ssl/corp-root.pem \
+  HTTPS_PROXY=http://proxy.corp:3128 \
+  shogo worker start --debug
+```
+
+`shogo worker start --debug` runs a preflight that includes a proxy-reachability
+check when `HTTPS_PROXY` is set.
+
+## Architecture & licensing
+
+The worker is split into two processes that talk over localhost only:
+
+```
+┌────────────────────────────────────┐    ┌────────────────────────────────────┐
+│  shogo (this package)              │    │  agent-runtime                     │
+│  ── MIT ────────────────────────── │    │  ── AGPL-3.0-or-later ──────────── │
+│                                    │    │                                    │
+│  • CLI (login / start / stop)      │    │  • Runs your agents                │
+│  • WorkerTunnel: HTTP heartbeat +  ├────►  • Tools, LLM proxy, plans         │
+│    on-demand WS to Shogo Cloud     │    │                                    │
+│  • WorkerRuntimeManager: spawns    │    │                                    │
+│    one runtime per project         │    │                                    │
+│                                    │    │                                    │
+│  Spawned by you / systemd / etc.   │    │  Spawned by the worker (process    │
+│                                    │    │  boundary; not linked as library)  │
+└────────────────────────────────────┘    └────────────────────────────────────┘
+```
+
+The MIT worker discovers and spawns the AGPL runtime as a separate OS process —
+no library link, no dynamic import, no embed. This keeps the licenses cleanly
+separated: you may consume `@shogo-ai/worker` from MIT / Apache-2.0 / proprietary
+code without AGPL infecting it.
+
+The runtime spawns themselves are managed by `WorkerRuntimeManager`: per-project
+port allocation, env injection, restart-with-backoff, idle eviction, and health
+checks. The same code path is consumed by Shogo Desktop (`apps/api`) for its own
+agent runtimes — so any improvement made here ships to both.
+
+## Programmatic use
+
+Both core classes are exposed for direct embedding (e.g. building your own
+desktop wrapper):
+
+```ts
+import { WorkerTunnel, WorkerRuntimeManager } from '@shogo-ai/worker'
+
+const runtimeManager = new WorkerRuntimeManager({
+  defaultSpawnConfig: { cloudUrl: 'https://studio.shogo.ai', apiKey: process.env.SHOGO_API_KEY! },
+})
+
+const tunnel = new WorkerTunnel({
+  apiKey: process.env.SHOGO_API_KEY!,
+  cloudUrl: 'https://studio.shogo.ai',
+  resolver: runtimeManager,         // implements RuntimeResolver
+  kind: 'cli-worker',
+  onAuthRevoked: (reason) => { /* re-login UX */ },
+})
+tunnel.start()
+```
+
+## Troubleshooting
+
+```bash
+shogo worker start --debug         # run preflight checks
+shogo worker logs --follow         # tail live logs
+SHOGO_DEBUG=1 shogo worker status  # verbose errors
+
+# Runtime missing?
+shogo runtime where     # see what's resolved
+shogo runtime install   # (re)download the latest stable binary
+```
+
+## Links
+
+- [Cloud Agent: My Machines guide](../../docs/cloud-agent-my-machines.md) — full
+  walk-through, security model, deploy patterns
+- [Networking & firewall guide](../../docs/my-machines-networking.md)
+- Source: [github.com/shogo-ai/shogo-ai](https://github.com/shogo-ai/shogo-ai)

package/bin/shogo.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+//
+// `shogo` CLI entry shim. Picks an execution mode in this order:
+//
+//   1. Compiled per-platform binary at $PREFIX/dist/shogo   (in the
+//      tarball release — Bun bundled, no runtime deps).
+//   2. Bundled JS at ../dist/cli.mjs                        (npm install
+//      with no Bun on PATH — Node ESM-loadable).
+//   3. Source TS at ../src/cli.ts                            (monorepo
+//      / `bun link`ed dev, requires Bun or tsx).
+import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+
+const compiledBin = join(__dirname, '..', 'dist', process.platform === 'win32' ? 'shogo.exe' : 'shogo');
+const distEntry = join(__dirname, '..', 'dist', 'cli.mjs');
+const srcEntry = join(__dirname, '..', 'src', 'cli.ts');
+
+if (existsSync(compiledBin)) {
+  const child = spawn(compiledBin, args, { stdio: 'inherit' });
+  child.on('exit', (code) => process.exit(code ?? 0));
+} else if (existsSync(distEntry)) {
+  await import(distEntry);
+} else if (existsSync(srcEntry)) {
+  const runner = process.versions.bun ? 'bun' : 'tsx';
+  const child = spawn(runner, [srcEntry, ...args], { stdio: 'inherit' });
+  child.on('exit', (code) => process.exit(code ?? 0));
+} else {
+  console.error('shogo: no executable entry found (looked for dist/shogo, dist/cli.mjs, src/cli.ts)');
+  console.error('       Reinstall with `npm i -g @shogo-ai/worker` or rebuild via `bun run build`.');
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@shogo-ai/worker",
+  "version": "1.7.4",
+  "description": "Shogo Cloud Agent Worker — run Shogo agents on your own machine (laptop, devbox, CI).",
+  "license": "MIT",
+  "author": "Shogo Technologies, Inc.",
+  "homepage": "https://shogo.ai/docs/cloud-agent/my-machines",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shogo-labs/shogo-ai.git",
+    "directory": "packages/shogo-worker"
+  },
+  "bin": {
+    "shogo": "./bin/shogo.mjs"
+  },
+  "main": "./src/cli.ts",
+  "type": "module",
+  "exports": {
+    ".": "./src/cli.ts",
+    "./tunnel": "./src/lib/tunnel.ts",
+    "./runtime-manager": "./src/lib/runtime-manager.ts",
+    "./runtime-resolver": "./src/lib/runtime-resolver.ts",
+    "./runtime-install": "./src/lib/runtime-install.ts",
+    "./cloud-login": "./src/lib/cloud-login.ts",
+    "./paths": "./src/lib/paths.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "bun src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "bun run build:js",
+    "build:js": "bun build --target=node --format=esm --minify --external bun --external @shogo-ai/sdk --external commander --external picocolors --outdir dist src/cli.ts && mv dist/cli.js dist/cli.mjs",
+    "build:bin:darwin-arm64": "bun build --compile --minify --target=bun-darwin-arm64 src/cli.ts --outfile dist/shogo-darwin-arm64",
+    "build:bin:darwin-x64": "bun build --compile --minify --target=bun-darwin-x64   src/cli.ts --outfile dist/shogo-darwin-x64",
+    "build:bin:linux-x64": "bun build --compile --minify --target=bun-linux-x64    src/cli.ts --outfile dist/shogo-linux-x64",
+    "build:bin:linux-arm64": "bun build --compile --minify --target=bun-linux-arm64  src/cli.ts --outfile dist/shogo-linux-arm64",
+    "build:bin:all": "bun run build:bin:darwin-arm64 && bun run build:bin:darwin-x64 && bun run build:bin:linux-x64 && bun run build:bin:linux-arm64",
+    "prepublishOnly": "bun run typecheck"
+  },
+  "dependencies": {
+    "@shogo-ai/sdk": "workspace:*",
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * Shogo Worker CLI — entry.
+ *
+ * `shogo login`                       — save an API key to ~/.shogo/config.json
+ * `shogo worker start [flags]`        — pair this machine with Shogo Cloud
+ * `shogo worker stop`                 — stop the local worker
+ * `shogo worker status`               — show running/stopped
+ * `shogo worker logs [--follow]`      — tail worker logs
+ * `shogo config show | set <k> <v>`   — inspect/modify config
+ */
+import { Command } from 'commander';
+import pc from 'picocolors';
+import { runStart } from './commands/start.ts';
+import { runStop } from './commands/stop.ts';
+import { runStatus } from './commands/status.ts';
+import { runLogs } from './commands/logs.ts';
+import { runLogin } from './commands/login.ts';
+import { runConfigShow, runConfigSet } from './commands/config.ts';
+import {
+  runRuntimeInstall,
+  runRuntimeUpdate,
+  runRuntimeVersion,
+  runRuntimeWhere,
+} from './commands/runtime.ts';
+
+const VERSION = '0.1.0';
+
+const program = new Command();
+program
+  .name('shogo')
+  .description('Shogo Cloud Agent Worker — run Shogo agents on your own machine.')
+  .version(VERSION);
+
+program
+  .command('login')
+  .description('Pair this machine with Shogo Cloud (browser device flow, or --api-key for CI)')
+  .option('--api-key <key>', 'CI escape hatch — skip the browser flow and use a key directly')
+  .option('--cloud-url <url>', 'Shogo Cloud URL (default: https://studio.shogo.ai)')
+  .option('--name <name>', 'Device label shown in the dashboard (default: hostname)')
+  .option('--workspace <id>', 'Pre-select a workspace on the bridge picker')
+  .option('--no-browser', 'Do not auto-open the browser; print the URL instead')
+  .action((flags) => handle(() => runLogin(flags)));
+
+const worker = program.command('worker').description('Manage the local worker process');
+
+worker
+  .command('start')
+  .description('Start the worker and pair with Shogo Cloud')
+  .option('--name <name>', 'Instance name shown in the dashboard (default: hostname)')
+  .option('--worker-dir <path>', 'Working directory for the worker (default: $PWD)')
+  .option('--api-key <key>', 'API key (overrides config/env)')
+  .option('--cloud-url <url>', 'Shogo Cloud URL')
+  .option('--port <port>', 'Local HTTP port for the embedded API')
+  .option('--proxy <url>', 'HTTPS proxy (overrides HTTPS_PROXY env)')
+  .option('--project <id>', 'Pin to a single project (default: multi-project on demand)')
+  .option('--runtime-bin <path>', 'Override the agent-runtime binary path')
+  .option('--debug', 'Run preflight checks before starting')
+  .option('--foreground', 'Run in foreground (don\'t detach)')
+  .action((flags) => handle(() => runStart(flags)));
+
+worker
+  .command('stop')
+  .description('Stop the running worker')
+  .action(() => handle(runStop));
+
+worker
+  .command('status')
+  .description('Show worker status')
+  .action(() => handle(runStatus));
+
+worker
+  .command('logs')
+  .description('Tail worker logs from ~/.shogo/logs/worker.log')
+  .option('-f, --follow', 'Follow the log (tail -F)')
+  .option('--err', 'Show stderr log instead')
+  .action((flags) => handle(() => runLogs(flags)));
+
+const runtime = program
+  .command('runtime')
+  .description('Install / inspect the local agent-runtime binary');
+runtime
+  .command('install')
+  .description('Download + verify the agent-runtime tarball into ~/.shogo/runtime/')
+  .option('--channel <channel>', 'stable | beta | nightly (default: stable)')
+  .option('--version <version>', 'install a specific version (e.g. 0.1.0)')
+  .option('--base-url <url>', 'override release base URL (default: GitHub Releases)')
+  .option('--force', 'reinstall even if the same version is already on disk')
+  .action((flags) => handle(() => runRuntimeInstall(flags)));
+runtime
+  .command('version')
+  .description('Print the installed agent-runtime version')
+  .action(() => handle(() => runRuntimeVersion()));
+runtime
+  .command('where')
+  .description('Print the resolved agent-runtime binary path')
+  .action(() => handle(() => runRuntimeWhere()));
+runtime
+  .command('update')
+  .description('Update agent-runtime to the latest in its channel')
+  .option('--channel <channel>', 'override channel (defaults to whatever is installed)')
+  .option('--base-url <url>', 'override release base URL')
+  .action((flags) => handle(() => runRuntimeUpdate(flags)));
+
+const config = program.command('config').description('Inspect or modify ~/.shogo/config.json');
+config
+  .command('show')
+  .description('Print current config (API key masked)')
+  .action(() => handle(runConfigShow));
+config
+  .command('set <key> <value>')
+  .description('Set apiKey / cloudUrl / name / workerDir / port')
+  .action((k: string, v: string) => handle(() => runConfigSet(k, v)));
+
+program.showHelpAfterError(pc.dim('\n(use --help for usage)'));
+program.parseAsync(process.argv);
+
+async function handle(fn: () => Promise<void> | void): Promise<void> {
+  try {
+    await fn();
+  } catch (err: any) {
+    console.error(pc.red(`✗ ${err?.message ?? err}`));
+    if (process.env.SHOGO_DEBUG) console.error(err?.stack);
+    process.exit(1);
+  }
+}

package/src/commands/config.ts

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+import pc from 'picocolors';
+import { loadConfig, saveConfig } from '../lib/config.ts';
+import { CONFIG_FILE } from '../lib/paths.ts';
+
+export async function runConfigShow(): Promise<void> {
+  const cfg = loadConfig();
+  if (Object.keys(cfg).length === 0) {
+    console.log(pc.dim('(no config — run `shogo login` or `shogo config set`)'));
+    return;
+  }
+  const masked = { ...cfg, apiKey: cfg.apiKey ? `***${cfg.apiKey.slice(-4)}` : undefined };
+  console.log(pc.dim(`file: ${CONFIG_FILE}`));
+  console.log(JSON.stringify(masked, null, 2));
+}
+
+export async function runConfigSet(key: string, value: string): Promise<void> {
+  const allowed = ['apiKey', 'cloudUrl', 'name', 'workerDir', 'port'] as const;
+  if (!allowed.includes(key as any)) {
+    console.error(pc.red(`Unknown key: ${key}`));
+    console.error(pc.dim(`Allowed: ${allowed.join(', ')}`));
+    process.exit(1);
+  }
+  const cfg = loadConfig();
+  (cfg as any)[key] = key === 'port' ? parseInt(value, 10) : value;
+  saveConfig(cfg);
+  console.log(pc.green(`✓ ${key} set`));
+}

package/src/commands/login.ts

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * `shogo login` — pair this machine with Shogo Cloud.
+ *
+ * Two modes, in priority order:
+ *
+ *   1. `--api-key <key>` flag, or `SHOGO_API_KEY` env var
+ *      → CI / headless mode. Validate against cloud, save, done.
+ *
+ *   2. Interactive (default)
+ *      → Poll-based device flow (see lib/cloud-login.ts):
+ *          POST /api/cli/login/start  → state + authUrl
+ *          open authUrl in browser    → user approves on cloud
+ *          GET  /api/cli/login/poll   → key once approved
+ *
+ * The minted key is written to ~/.shogo/config.json with mode 0600 so
+ * other local users can't read it. The same file is what
+ * `shogo worker start` reads on boot.
+ *
+ * The legacy "paste a shogo_sk_ key at the prompt" flow is still
+ * supported via `--api-key`; it just isn't the default any more.
+ */
+import pc from 'picocolors';
+import { loadConfig, saveConfig } from '../lib/config.ts';
+import { runCloudLogin, CloudLoginError } from '../lib/cloud-login.ts';
+import { getOrCreateDeviceId } from '../lib/device-id.ts';
+
+export interface LoginFlags {
+  apiKey?: string;
+  cloudUrl?: string;
+  name?: string;
+  workspace?: string;
+  noBrowser?: boolean;
+}
+
+const DEFAULT_CLOUD_URL = 'https://studio.shogo.ai';
+
+export async function runLogin(flags: LoginFlags): Promise<void> {
+  const cfg = loadConfig();
+  const cloudUrl = (flags.cloudUrl || cfg.cloudUrl || DEFAULT_CLOUD_URL).replace(/\/$/, '');
+
+  const escapeKey = flags.apiKey || process.env.SHOGO_API_KEY;
+  if (escapeKey) {
+    await loginWithApiKey({ key: escapeKey, cloudUrl, cfg, name: flags.name });
+    return;
+  }
+
+  const deviceId = getOrCreateDeviceId();
+  let result;
+  try {
+    result = await runCloudLogin({
+      cloudUrl,
+      deviceId,
+      deviceName: flags.name,
+      workspaceId: flags.workspace,
+      openBrowser: !flags.noBrowser,
+    });
+  } catch (err: any) {
+    if (err instanceof CloudLoginError) {
+      console.error(pc.red(`✗ ${err.message}`));
+      if (err.kind === 'transport') {
+        console.error(pc.dim(`  If your network blocks browsers, run with --api-key <key> instead.`));
+      }
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  cfg.apiKey = result.key;
+  cfg.cloudUrl = cloudUrl;
+  if (flags.name) cfg.name = flags.name;
+  saveConfig(cfg);
+
+  console.log('');
+  console.log(pc.green('✓ Signed in to Shogo Cloud'));
+  if (result.workspace) console.log(pc.dim('  workspace: ') + result.workspace);
+  if (result.email) console.log(pc.dim('  email:     ') + result.email);
+  console.log(pc.dim('  saved to:  ') + '~/.shogo/config.json');
+  console.log('');
+  console.log(pc.dim('  next: ') + 'shogo worker start');
+}
+
+interface ApiKeyOpts {
+  key: string;
+  cloudUrl: string;
+  cfg: ReturnType<typeof loadConfig>;
+  name?: string;
+}
+
+async function loginWithApiKey({ key, cloudUrl, cfg, name }: ApiKeyOpts): Promise<void> {
+  if (!/^shogo_sk_/.test(key)) {
+    console.error(pc.red('✗ API key should start with "shogo_sk_". Copy it verbatim from the API Keys page.'));
+    process.exit(1);
+  }
+
+  // Mirror apps/api/src/routes/local-auth.ts: re-validate against cloud
+  // before persisting so the user gets immediate feedback on a bad key.
+  let validation: { valid?: boolean; error?: string; workspace?: { name?: string } | null; user?: { email?: string } | null };
+  try {
+    const res = await fetch(`${cloudUrl}/api/api-keys/validate`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ key }),
+      signal: AbortSignal.timeout(10_000),
+    });
+    validation = await res.json().catch(() => ({} as any)) as typeof validation;
+    if (!res.ok || !validation?.valid) {
+      console.error(pc.red(`✗ ${validation?.error || `Cloud rejected the key (HTTP ${res.status}).`}`));
+      process.exit(1);
+    }
+  } catch (err: any) {
+    console.error(pc.red(`✗ Cannot reach Shogo Cloud at ${cloudUrl}: ${err?.message ?? err}`));
+    process.exit(1);
+  }
+
+  cfg.apiKey = key;
+  cfg.cloudUrl = cloudUrl;
+  if (name) cfg.name = name;
+  saveConfig(cfg);
+
+  console.log(pc.green('✓ API key saved to ~/.shogo/config.json'));
+  if (validation.workspace?.name) console.log(pc.dim('  workspace: ') + validation.workspace.name);
+  if (validation.user?.email) console.log(pc.dim('  email:     ') + validation.user.email);
+  console.log(pc.dim('  next: ') + 'shogo worker start');
+}

package/src/commands/logs.ts

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+import { spawn } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import pc from 'picocolors';
+import { WORKER_LOG, WORKER_ERR } from '../lib/paths.ts';
+
+export interface LogsFlags { follow?: boolean; err?: boolean }
+
+export async function runLogs(flags: LogsFlags): Promise<void> {
+  const file = flags.err ? WORKER_ERR : WORKER_LOG;
+  if (!existsSync(file)) {
+    console.log(pc.dim('No logs yet.'));
+    return;
+  }
+  const args = flags.follow ? ['-F', '-n', '200', file] : ['-n', '200', file];
+  const child = spawn('tail', args, { stdio: 'inherit' });
+  child.on('exit', (code) => process.exit(code ?? 0));
+
+  if (!flags.follow) {
+    const size = statSync(file).size;
+    if (size === 0) console.log(pc.dim('(log file is empty)'));
+  }
+}