@almyty/cli 1.2.0 → 1.3.0

package/README.md

@@ -1,40 +1,102 @@
 # @almyty/cli
 
-Umbrella CLI for almyty. One install, every command.
+Umbrella CLI for almyty. One install, one login, every command.
 
 ## Quick start
 
 ```bash
 $ npm install -g @almyty/cli
+$ almyty                  # a short tour
 $ almyty login
 $ almyty agents list
 ```
 
+`almyty` on its own prints a five-line tour. `almyty help` prints the
+full reference, and `almyty <command> --help` prints that command's own
+options — the umbrella forwards `--help` to the package it delegates to.
+
 ## Commands
 
 | Command | Delegates to | Description |
 |---------|-------------|-------------|
-| `almyty login` | `@almyty/auth` | Browser-based login |
+| `almyty login` | `@almyty/auth` | Browser-based login (writes `~/.almyty/credentials.json`) |
 | `almyty logout` | `@almyty/auth` | Remove stored credentials |
-| `almyty whoami` | `@almyty/auth` | Show current identity |
-| `almyty agents <cmd>` | `@almyty/agents` | List, run, inspect agents |
-| `almyty chat [org/slug]` | `@almyty/chat` | Interactive chat REPL |
-| `almyty skills <cmd>` | `@almyty/skills` | Install and manage skills |
-| `almyty mcp <args>` | `@almyty/mcp-server` | Start MCP server |
+| `almyty whoami` | `@almyty/auth` | Show the current identity and when it expires |
+| `almyty auth <cmd>` | `@almyty/auth` | The same three, spelled out |
+| `almyty agents <cmd>` | `@almyty/agents` | List, run, inspect and trace agents |
+| `almyty chat [ref]` | `@almyty/chat` | Interactive chat REPL |
+| `almyty skills <cmd>` | `@almyty/skills` | Install API skills into AI coding agents |
+| `almyty models <cmd>` | `@almyty/models` | Model catalog: cards, validation, deployments |
+| `almyty connections <cmd>` | `@almyty/connections` | Connect third-party accounts, validate, grant |
+| `almyty runner <cmd>` | `@almyty/runner` | Run agents on this machine as a daemon |
+| `almyty mcp <args>` | `@almyty/mcp-server` | Serve your agents and tools over MCP |
 | `almyty acp <args>` | `@almyty/acp-server` | Serve an agent over the Agent Client Protocol |
-| `almyty runner <cmd>` | `@almyty/runner` | Run a machine daemon (`runner start`, `runner status`) |
+
+Handled by the umbrella itself:
+
+| Command | Description |
+|---------|-------------|
+| `almyty help`, `--help` | The full command reference |
+| `almyty version`, `--version` | The installed version |
+| `almyty completion <shell>` | A completion script for `bash`, `zsh` or `fish` |
+
+An unknown command exits `2` and suggests the nearest real one
+(`almyty agent list` → "Did you mean `almyty agents`?").
+
+## Shell completion
+
+```bash
+# bash — add to ~/.bashrc
+eval "$(almyty completion bash)"
+
+# zsh — add to ~/.zshrc
+eval "$(almyty completion zsh)"
+
+# fish
+almyty completion fish > ~/.config/fish/completions/almyty.fish
+```
+
+## Exit codes
+
+The same table in every almyty CLI, so `almyty <anything>` can be
+scripted the same way:
+
+| Code | Meaning |
+|------|---------|
+| `0` | success |
+| `1` | unexpected error |
+| `2` | usage error (bad flags, unknown command) |
+| `3` | not authenticated — run `almyty login` |
+| `4` | not found (agent, gateway, skill, or run) |
+| `5` | the operation ran and failed |
+
+```bash
+almyty agents run deploy-check --watch || case $? in
+  3) almyty login ;;
+  5) echo "the check failed"; exit 1 ;;
+esac
+```
 
 ## Standalone packages
 
-Every subcommand is also available as a standalone package via `npx`:
+Every subcommand is also a standalone package, so the umbrella is a
+convenience and not a requirement:
 
 ```bash
+$ npx @almyty/auth login
 $ npx @almyty/agents list
 $ npx @almyty/chat myorg/my-bot
-$ npx @almyty/skills install @org/gateway
+$ npx @almyty/skills install org/gateway
 ```
 
-All packages share the same credentials file (`~/.almyty/credentials.json`), so logging in once works everywhere.
+They all read the same credentials file (`~/.almyty/credentials.json`),
+so logging in once works everywhere.
+
+## Piping
+
+Every read command takes `--json` and prints nothing but JSON on stdout.
+No almyty CLI emits ANSI colour of its own, so `NO_COLOR` is honoured
+and there is nothing to strip when you pipe.
 
 ## About almyty
 
@@ -42,8 +104,10 @@ almyty is the full-stack platform for AI agents, agnostic by design: any LLM, an
 API turned into tools, served over MCP, A2A, UTCP, and Agent Skills. Open source,
 no lock-in.
 
-- Website — https://almyty.com
-- Docs — https://docs.almyty.com
-- Source — https://github.com/almyty-inc/almyty
+- Website: https://almyty.com
+- Docs: https://docs.almyty.com
+- Source: https://github.com/almyty-inc/almyty
+
+This CLI is part of the `@almyty/*` suite (versioned together at 1.x) and works with the almyty platform 0.1 and later.
 
 Apache-2.0 © Almyty Inc.

package/dist/commands.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The umbrella's routing table, help text, and shell completion.
+ *
+ * Kept out of index.ts so it can be unit-tested without spawning a
+ * child process: every entry here must be listed in the help text and
+ * must name a package the umbrella actually depends on, and there are
+ * tests that assert both.
+ */
+export interface Subcommand {
+    /** Package name to delegate to. */
+    pkg: string;
+    /**
+     * Optional argv prefix injected before the user-supplied args.
+     * Used for top-level shortcuts like `almyty login` -> `@almyty/auth login`.
+     */
+    prefixArgs?: string[];
+    /** Short help line shown by `almyty help`. */
+    help: string;
+    /** Section heading this command is grouped under in the help output. */
+    group: string;
+    /** Subcommand names, for shell completion. Empty when it takes free-form args. */
+    subcommands?: string[];
+}
+/**
+ * Top-level subcommand routing table. Order = display order in help.
+ *
+ * Every `pkg` here must be a dependency of @almyty/cli. `models` and
+ * `connections` were listed in the help text while the umbrella did
+ * not depend on them, so `almyty models list` answered "package
+ * @almyty/models is not installed" for a command its own --help
+ * advertised.
+ */
+export declare const SUBCOMMANDS: Record<string, Subcommand>;
+/** Commands the umbrella answers itself, rather than delegating. */
+export declare const BUILTIN_COMMANDS: readonly ["help", "version", "completion"];
+/** Every name `almyty <x>` accepts, for completion and suggestions. */
+export declare function allCommandNames(): string[];
+/**
+ * A short tour, printed when `almyty` is run with no arguments.
+ *
+ * A bare `almyty` used to print the entire command reference, which is
+ * the least useful thing to show someone who has just installed it and
+ * does not yet know what the product does.
+ */
+export declare function tourText(version: string): string;
+/** The full command reference, printed by `almyty help` / `--help`. */
+export declare function helpText(version: string): string;
+/**
+ * The closest command name to what the user typed, or null.
+ * `almyty agent list` (singular) should not just say "unknown command".
+ */
+export declare function suggestCommand(input: string): string | null;
+export declare const COMPLETION_SHELLS: readonly ["bash", "zsh", "fish"];
+export type CompletionShell = (typeof COMPLETION_SHELLS)[number];
+export declare function isCompletionShell(value: string): value is CompletionShell;
+/**
+ * A completion script for one shell. Static — it lists the top-level
+ * commands and each one's own subcommands from the table above, so it
+ * never has to shell out to the sub-CLIs to build a candidate list.
+ */
+export declare function completionScript(shell: CompletionShell): string;

package/dist/commands.js

@@ -0,0 +1,204 @@
+/**
+ * The umbrella's routing table, help text, and shell completion.
+ *
+ * Kept out of index.ts so it can be unit-tested without spawning a
+ * child process: every entry here must be listed in the help text and
+ * must name a package the umbrella actually depends on, and there are
+ * tests that assert both.
+ */
+/**
+ * Top-level subcommand routing table. Order = display order in help.
+ *
+ * Every `pkg` here must be a dependency of @almyty/cli. `models` and
+ * `connections` were listed in the help text while the umbrella did
+ * not depend on them, so `almyty models list` answered "package
+ * @almyty/models is not installed" for a command its own --help
+ * advertised.
+ */
+export const SUBCOMMANDS = {
+    // Auth shortcuts at top level (gh-style: `almyty login` not `almyty auth login`)
+    login: { pkg: '@almyty/auth', prefixArgs: ['login'], group: 'Auth', help: 'Browser-based login (writes ~/.almyty/credentials.json)' },
+    logout: { pkg: '@almyty/auth', prefixArgs: ['logout'], group: 'Auth', help: 'Remove stored credentials' },
+    whoami: { pkg: '@almyty/auth', prefixArgs: ['whoami'], group: 'Auth', help: 'Show the current identity' },
+    auth: { pkg: '@almyty/auth', group: 'Auth', help: 'Auth subcommands', subcommands: ['login', 'logout', 'whoami'] },
+    // Domain CLIs
+    agents: { pkg: '@almyty/agents', group: 'Agents', help: 'List, run, and inspect agents', subcommands: ['list', 'get', 'run', 'runs', 'inspect', 'executions', 'trace', 'cancel'] },
+    chat: { pkg: '@almyty/chat', group: 'Agents', help: 'Interactive chat REPL with an agent' },
+    skills: { pkg: '@almyty/skills', group: 'Skills', help: 'Install API skills into AI coding agents', subcommands: ['install', 'list', 'search', 'run', 'installed', 'remove', 'gateways', 'daemon', 'watch'] },
+    models: { pkg: '@almyty/models', group: 'Platform', help: 'Model catalog: cards, validation, deployments' },
+    connections: { pkg: '@almyty/connections', group: 'Platform', help: 'Connect third-party accounts: connectors, validate, grants' },
+    runner: { pkg: '@almyty/runner', group: 'Serving', help: 'Run agents on this machine as a daemon' },
+    mcp: { pkg: '@almyty/mcp-server', group: 'Serving', help: 'Serve your agents and tools over MCP' },
+    acp: { pkg: '@almyty/acp-server', group: 'Serving', help: 'Serve an agent over the Agent Client Protocol' },
+};
+/** Commands the umbrella answers itself, rather than delegating. */
+export const BUILTIN_COMMANDS = ['help', 'version', 'completion'];
+/** Every name `almyty <x>` accepts, for completion and suggestions. */
+export function allCommandNames() {
+    return [...Object.keys(SUBCOMMANDS), ...BUILTIN_COMMANDS];
+}
+/**
+ * A short tour, printed when `almyty` is run with no arguments.
+ *
+ * A bare `almyty` used to print the entire command reference, which is
+ * the least useful thing to show someone who has just installed it and
+ * does not yet know what the product does.
+ */
+export function tourText(version) {
+    return `almyty v${version} — build, run, and serve AI agents.
+
+Start here:
+  almyty login                     Authenticate this machine
+  almyty agents list               See the agents in your organization
+  almyty agents run <agent>        Run one and print its output
+  almyty chat <agent>              Talk to one in your terminal
+  almyty skills install <ref>      Teach your coding agent an API
+
+  almyty help                      Every command, grouped
+  almyty <command> --help          Detail for one command
+
+Docs: https://docs.almyty.com`;
+}
+/** The full command reference, printed by `almyty help` / `--help`. */
+export function helpText(version) {
+    const groups = new Map();
+    const width = Math.max(...Object.keys(SUBCOMMANDS).map((n) => n.length), 'completion <shell>'.length);
+    for (const [name, sub] of Object.entries(SUBCOMMANDS)) {
+        const lines = groups.get(sub.group) ?? [];
+        lines.push(`  ${name.padEnd(width)}  ${sub.help}`);
+        groups.set(sub.group, lines);
+    }
+    const sections = [...groups.entries()]
+        .map(([group, lines]) => `${group}:\n${lines.join('\n')}`)
+        .join('\n\n');
+    return `almyty CLI v${version}
+
+Usage:
+  almyty <command> [args]
+  almyty <command> --help          Full options for that command
+
+${sections}
+
+Other:
+  ${'help'.padEnd(width)}  Show this help
+  ${'version'.padEnd(width)}  Print the version
+  ${'completion <shell>'.padEnd(width)}  Print a completion script (bash, zsh, fish)
+
+Exit codes (the same in every almyty CLI):
+  0  success
+  1  unexpected error
+  2  usage error (bad flags, unknown command)
+  3  not authenticated — run \`almyty login\`
+  4  not found (agent, gateway, skill, or run)
+  5  the operation ran and failed
+
+Every subcommand is also a standalone package, so nothing here is
+required in order to use one of them:
+
+  npx @almyty/auth login
+  npx @almyty/agents list
+  npx @almyty/chat my-research-bot
+  npx @almyty/skills install org/gateway
+
+They all read the same credentials file (~/.almyty/credentials.json),
+so \`almyty login\` logs all of them in at once.`;
+}
+/** Levenshtein distance, capped — only used to suggest a command name. */
+function distance(a, b) {
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    let prev = Array.from({ length: cols }, (_, j) => j);
+    for (let i = 1; i < rows; i++) {
+        const curr = [i];
+        for (let j = 1; j < cols; j++) {
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = curr;
+    }
+    return prev[cols - 1];
+}
+/**
+ * The closest command name to what the user typed, or null.
+ * `almyty agent list` (singular) should not just say "unknown command".
+ */
+export function suggestCommand(input) {
+    const typed = input.toLowerCase();
+    let best = null;
+    let bestScore = Infinity;
+    for (const name of allCommandNames()) {
+        const d = distance(typed, name);
+        if (d < bestScore) {
+            bestScore = d;
+            best = name;
+        }
+    }
+    const tolerance = typed.length <= 4 ? 1 : 2;
+    return best !== null && bestScore <= tolerance ? best : null;
+}
+export const COMPLETION_SHELLS = ['bash', 'zsh', 'fish'];
+export function isCompletionShell(value) {
+    return COMPLETION_SHELLS.includes(value);
+}
+/**
+ * A completion script for one shell. Static — it lists the top-level
+ * commands and each one's own subcommands from the table above, so it
+ * never has to shell out to the sub-CLIs to build a candidate list.
+ */
+export function completionScript(shell) {
+    const top = allCommandNames().join(' ');
+    if (shell === 'bash') {
+        const cases = Object.entries(SUBCOMMANDS)
+            .filter(([, s]) => s.subcommands?.length)
+            .map(([name, s]) => `    ${name}) subs="${s.subcommands.join(' ')}" ;;`)
+            .join('\n');
+        return `# almyty bash completion — add to ~/.bashrc:
+#   eval "$(almyty completion bash)"
+_almyty_complete() {
+  local cur prev subs
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "${top}" -- "$cur") )
+    return
+  fi
+  subs=""
+  case "\${COMP_WORDS[1]}" in
+${cases}
+    completion) subs="bash zsh fish" ;;
+  esac
+  if [ -n "$subs" ] && [ "$COMP_CWORD" -eq 2 ]; then
+    COMPREPLY=( $(compgen -W "$subs" -- "$cur") )
+  fi
+}
+complete -F _almyty_complete almyty`;
+    }
+    if (shell === 'zsh') {
+        const descs = Object.entries(SUBCOMMANDS)
+            .map(([name, s]) => `    '${name}:${s.help.replace(/'/g, '')}'`)
+            .join('\n');
+        return `# almyty zsh completion — add to ~/.zshrc:
+#   eval "$(almyty completion zsh)"
+_almyty() {
+  local -a commands
+  commands=(
+${descs}
+    'help:Show help'
+    'version:Print the version'
+    'completion:Print a shell completion script'
+  )
+  if (( CURRENT == 2 )); then
+    _describe -t commands 'almyty command' commands
+  fi
+}
+compdef _almyty almyty`;
+    }
+    const fishLines = Object.entries(SUBCOMMANDS)
+        .map(([name, s]) => `complete -c almyty -n __fish_use_subcommand -a ${name} -d '${s.help.replace(/'/g, '')}'`)
+        .join('\n');
+    return `# almyty fish completion — save as ~/.config/fish/completions/almyty.fish:
+#   almyty completion fish > ~/.config/fish/completions/almyty.fish
+${fishLines}
+complete -c almyty -n __fish_use_subcommand -a help -d 'Show help'
+complete -c almyty -n __fish_use_subcommand -a version -d 'Print the version'
+complete -c almyty -n __fish_use_subcommand -a completion -d 'Print a shell completion script'`;
+}

package/dist/exit-codes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Exit codes shared by every almyty CLI.
+ *
+ * Scripts need to tell "you are not logged in" apart from "that agent
+ * does not exist" apart from "the run you asked for failed" without
+ * grepping stderr. Every almyty CLI uses this same table, so
+ * `almyty agents run x || case $? in 3) almyty login;; esac` behaves
+ * the same whichever binary produced the code.
+ */
+export declare const EXIT: {
+    /** Success. */
+    readonly OK: 0;
+    /** Unexpected failure (a thrown error with no better classification). */
+    readonly ERROR: 1;
+    /** Bad or missing arguments, or an unknown command. */
+    readonly USAGE: 2;
+    /** No stored credential, or the API rejected the one we had. */
+    readonly AUTH: 3;
+    /** The named agent / gateway / skill / run does not exist. */
+    readonly NOT_FOUND: 4;
+    /** The command ran; the operation it asked for failed. */
+    readonly FAILED: 5;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+/** One line per code, for `--help` output and READMEs. */
+export declare const EXIT_CODE_HELP: string;

package/dist/exit-codes.js

@@ -0,0 +1,32 @@
+/**
+ * Exit codes shared by every almyty CLI.
+ *
+ * Scripts need to tell "you are not logged in" apart from "that agent
+ * does not exist" apart from "the run you asked for failed" without
+ * grepping stderr. Every almyty CLI uses this same table, so
+ * `almyty agents run x || case $? in 3) almyty login;; esac` behaves
+ * the same whichever binary produced the code.
+ */
+export const EXIT = {
+    /** Success. */
+    OK: 0,
+    /** Unexpected failure (a thrown error with no better classification). */
+    ERROR: 1,
+    /** Bad or missing arguments, or an unknown command. */
+    USAGE: 2,
+    /** No stored credential, or the API rejected the one we had. */
+    AUTH: 3,
+    /** The named agent / gateway / skill / run does not exist. */
+    NOT_FOUND: 4,
+    /** The command ran; the operation it asked for failed. */
+    FAILED: 5,
+};
+/** One line per code, for `--help` output and READMEs. */
+export const EXIT_CODE_HELP = [
+    '  0  success',
+    '  1  unexpected error',
+    '  2  usage error (bad flags, unknown command)',
+    '  3  not authenticated — run `almyty login`',
+    '  4  not found (agent, gateway, skill, or run)',
+    '  5  the operation ran and failed',
+].join('\n');

package/dist/index.d.ts

@@ -6,8 +6,7 @@
  *   almyty login
  *   almyty agents list
  *   almyty chat my-research-bot
- *   almyty skills install @org/gateway
- *   almyty mcp <args>
+ *   almyty skills install org/gateway
  *
  * The umbrella delegates each subcommand to a standalone @almyty/<thing>
  * package by spawning its bin. Each package can ALSO be invoked directly:
@@ -15,7 +14,6 @@
  *   npx @almyty/auth login
  *   npx @almyty/agents list
  *   npx @almyty/chat my-research-bot
- *   …
  *
  * The standalone packages and the umbrella stay in sync because they
  * share the same on-disk credentials store at ~/.almyty/credentials.json.

package/dist/index.js

@@ -6,8 +6,7 @@
  *   almyty login
  *   almyty agents list
  *   almyty chat my-research-bot
- *   almyty skills install @org/gateway
- *   almyty mcp <args>
+ *   almyty skills install org/gateway
  *
  * The umbrella delegates each subcommand to a standalone @almyty/<thing>
  * package by spawning its bin. Each package can ALSO be invoked directly:
@@ -15,84 +14,18 @@
  *   npx @almyty/auth login
  *   npx @almyty/agents list
  *   npx @almyty/chat my-research-bot
- *   …
  *
  * The standalone packages and the umbrella stay in sync because they
  * share the same on-disk credentials store at ~/.almyty/credentials.json.
  */
-import { spawn } from 'child_process';
-import { createRequire } from 'module';
-import { dirname, join } from 'path';
-import { existsSync } from 'fs';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { VERSION } from './version.js';
+import { EXIT } from './exit-codes.js';
+import { SUBCOMMANDS, completionScript, helpText, isCompletionShell, suggestCommand, tourText, COMPLETION_SHELLS, } from './commands.js';
 const require = createRequire(import.meta.url);
-const VERSION = '0.1.0';
-/**
- * Top-level subcommand routing table. Order = display order in help.
- */
-const SUBCOMMANDS = {
-    // Auth shortcuts at top level (gh-style: `almyty login` not `almyty auth login`)
-    login: { pkg: '@almyty/auth', prefixArgs: ['login'], help: 'Browser-based login' },
-    logout: { pkg: '@almyty/auth', prefixArgs: ['logout'], help: 'Remove stored credentials' },
-    whoami: { pkg: '@almyty/auth', prefixArgs: ['whoami'], help: 'Show the current identity' },
-    auth: { pkg: '@almyty/auth', help: 'Auth subcommands (login/logout/whoami)' },
-    // Domain CLIs
-    agents: { pkg: '@almyty/agents', help: 'List, run, and inspect agents' },
-    chat: { pkg: '@almyty/chat', help: 'Interactive chat REPL with an agent' },
-    skills: { pkg: '@almyty/skills', help: 'Install API skills into AI coding agents' },
-    mcp: { pkg: '@almyty/mcp-server', help: 'Run the MCP server proxy' },
-    acp: { pkg: '@almyty/acp-server', help: 'Run the ACP agent server' },
-    runner: { pkg: '@almyty/runner', help: 'Long-running daemon to run agents on this machine' },
-};
-function printHelp() {
-    console.log(`
-almyty CLI v${VERSION}
-
-Usage:
-  almyty <command> [args]
-
-Auth:
-  login                 Browser-based login (writes ~/.almyty/credentials.json)
-  logout                Remove stored credentials
-  whoami                Show the currently logged-in identity
-  auth <subcommand>     Pass-through to @almyty/auth
-
-Agents:
-  agents list                       List agents in your organization
-  agents get <ref>                  Show details for one agent
-  agents run <ref> [--input ...]    Invoke / start a run
-  agents runs <ref>                 List recent runs
-  agents cancel <ref> <runId>       Cancel an in-flight run
-
-Chat:
-  chat                  Interactive REPL — pick an agent from a menu
-  chat <ref>            Start chatting with that agent
-
-Skills:
-  skills install <ref>              Install skills into local AI coding agents
-  skills list [ref]                 List available skills
-  skills daemon                     Sync skills on a schedule
-  skills run <ref>                  Execute a skill once
-
-MCP:
-  mcp <args>            Run the MCP server proxy
-
-Runner:
-  runner start [--name n]    Start a runner daemon, register with the SaaS
-  runner status              Show local runner status
-
-Other:
-  help, --help          Show this help
-  version, --version    Show version
-
-Each subcommand maps to a standalone npm package. You can invoke any
-of them directly with npx:
-
-  npx @almyty/auth login
-  npx @almyty/agents list
-  npx @almyty/chat my-research-bot
-  npx @almyty/skills install @org/gateway
-`);
-}
 function resolveBinPath(packageName) {
     // Resolve the package's package.json to find its installation root,
     // then read the "bin" entry to find the actual script path.
@@ -133,8 +66,8 @@ function delegate(packageName, args) {
     if (!binPath) {
         console.error(`Error: package ${packageName} is not installed.`);
         console.error(`  Install it with: npm install -g ${packageName}`);
-        console.error(`  Or use:           npx ${packageName} ${args.join(' ')}`);
-        return Promise.resolve(1);
+        console.error(`  Or use:          npx ${packageName} ${args.join(' ')}`);
+        return Promise.resolve(EXIT.ERROR);
     }
     return new Promise((resolve) => {
         const child = spawn(process.execPath, [binPath, ...args], {
@@ -162,30 +95,49 @@ function delegate(packageName, args) {
                 process.kill(process.pid, signal);
                 return;
             }
-            resolve(code ?? 0);
+            resolve(code ?? EXIT.OK);
         });
         child.on('error', (err) => {
             console.error(`Failed to launch ${packageName}: ${err.message}`);
-            resolve(1);
+            resolve(EXIT.ERROR);
         });
     });
 }
 async function main() {
     const argv = process.argv.slice(2);
-    if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h' || argv[0] === 'help') {
-        printHelp();
+    // Bare `almyty` shows a short tour, not the full reference.
+    if (argv.length === 0) {
+        console.log(tourText(VERSION));
+        return;
+    }
+    if (argv[0] === '--help' || argv[0] === '-h' || argv[0] === 'help') {
+        console.log(helpText(VERSION));
         return;
     }
     if (argv[0] === '--version' || argv[0] === '-v' || argv[0] === 'version') {
         console.log(VERSION);
         return;
     }
+    if (argv[0] === 'completion') {
+        const shell = argv[1];
+        if (!shell || !isCompletionShell(shell)) {
+            console.error(`Usage: almyty completion <${COMPLETION_SHELLS.join('|')}>`);
+            process.exit(EXIT.USAGE);
+        }
+        console.log(completionScript(shell));
+        return;
+    }
     const cmd = argv[0];
     const sub = SUBCOMMANDS[cmd];
     if (!sub) {
         console.error(`Unknown command: ${cmd}`);
-        console.error(`Run \`almyty help\` for the list of commands.`);
-        process.exit(1);
+        const suggestion = suggestCommand(cmd);
+        if (suggestion)
+            console.error(`Did you mean \`almyty ${suggestion}\`?`);
+        console.error('Run `almyty help` for the list of commands.');
+        // Usage error, not a generic failure: a script can tell a typo
+        // apart from a command that ran and failed.
+        process.exit(EXIT.USAGE);
     }
     const passthroughArgs = [...(sub.prefixArgs ?? []), ...argv.slice(1)];
     const code = await delegate(sub.pkg, passthroughArgs);
@@ -193,5 +145,5 @@ async function main() {
 }
 main().catch((err) => {
     console.error(`Error: ${err.message}`);
-    process.exit(1);
+    process.exit(EXIT.ERROR);
 });

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare function readVersion(fallback?: string): string;
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,22 @@
+/**
+ * The CLI's own version, read from its package.json at startup.
+ *
+ * It used to be a hardcoded string, which drifted: `--version`
+ * answered 0.1.0 while the published package was 1.2.0, so a bug
+ * report never identified the build it came from. Both `dist/index.js`
+ * and `src/index.ts` sit one directory below the package root, so the
+ * same relative path resolves for the built bin and for `tsx src/index.ts`.
+ */
+import { readFileSync } from 'node:fs';
+export function readVersion(fallback = '0.0.0') {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
+        return typeof pkg.version === 'string' && pkg.version.length > 0
+            ? pkg.version
+            : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+export const VERSION = readVersion();

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@almyty/cli",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "publishConfig": {
     "access": "public"
   },
-  "description": "The almyty CLI \u2014 one login for agents, chat, skills, an MCP server, and a machine runner. Part of almyty, the full-stack platform for AI agents.",
+  "description": "The almyty CLI — one login for agents, chat, skills, an MCP server, and a machine runner. Part of almyty, the full-stack platform for AI agents.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -35,6 +35,8 @@
     "@almyty/agents": "^1.2.0",
     "@almyty/chat": "^1.2.0",
     "@almyty/skills": "^1.2.0",
+    "@almyty/models": "^1.2.0",
+    "@almyty/connections": "^1.2.0",
     "@almyty/mcp-server": "^1.2.0",
     "@almyty/acp-server": "^1.2.0",
     "@almyty/runner": "^1.2.0"
@@ -45,6 +47,12 @@
     "typescript": "^5.3.0",
     "vitest": "^4.1.0"
   },
+  "overrides": {
+    "@hono/node-server": "^2.0.5",
+    "fast-uri": "^3.1.5",
+    "ip-address": "^10.4.0",
+    "postcss": "^8.5.23"
+  },
   "homepage": "https://almyty.com",
   "repository": {
     "type": "git",