AI CLI

[TOC]

@fenying/ai-cli creates AI Agent workspaces and manages workspace-local skills and stories through the ai command.

Requirements

Node.js with Git available on PATH is required for Git-backed skill sources.

Development

Install dependencies and run the relevant quality checks:

npm install
npm run lint
npm run build
npm test

The TypeScript test suites live under src/test/. Every real CLI workspace and Git fixture is created beneath the operating system temporary directory, never in this repository; .ai/temp/ is only an initialized workspace entry that tests may assert.

Run the compiled command locally:

node dist/bin/ai.js --help

Commands

ai init
ai workspace set-external <true|on|false|off> [--dir PATH]
ai details
ai story new [--code|-c CODE] [--name|-n NAME]
ai story ls [--all]
ai story archive [CODE]
ai story unarchive [CODE]
ai story use [CODE]
ai story rm [CODE]
ai story patch
ai workspace ls
ai workspace history
ai workspace save
ai workspace reset
ai workspace fork <name> [--from <branch>|--checkpoint <commit>]
ai workspace rm <branch>
ai workspace use <branch>
ai skills install [--all] [--save-bundle|-b] <REPO_REF> [skill-name...]
ai skills bundle add [skill-name...]
ai skills bundle remove|rm [skill-name...]
ai skills update [--all] [skill-name...]
ai skills remove [skill-name...]
ai skills list [--bundle] [--show-desc] [REPO_REF]
ai skills show-install <skill-name>
ai completion generate <bash|powershell>
ai completion config <bash|powershell>

ai ws is an alias for ai workspace.

ai init creates missing workspace assets and, on the first run, adds /.agents/ to the root .gitignore and any existing .npmignore. When run again in a valid initialized workspace, it restores registered skills by running ai skills i without changing those ignore files. If an external workspace already exists at the configured or default location, initialization first asks whether to create a new workspace or restore the existing one. Escape or Cancel aborts without changing workspace files, links, or configuration. A noninteractive invocation fails when this choice is required.

When a terminal is interactive, omitting skill names from install, update, remove, or skills bundle commands opens a multi-select list. The list starts with a Select All item where that interaction applies; use --all with install or update to bypass it and process every eligible skill, including overwriting existing installed skills.

The interactive picker requires a terminal of at least 80 columns by 16 rows. Use Arrow keys, Home/End, Page Up/Page Down, Space, and Enter to navigate and confirm; Escape cancels the selection. Letter keys use case-insensitive skill name typeahead.

External Workspaces

Use ai workspace or its ai ws alias to keep the private workspace files outside a project Git repository. set-external true and set-external on always recreate the Git-backed external workspace from the project's local workspace files. Any existing external repository and its snapshot history are deleted; this command does not prompt to restore it. set-external false and set-external off restore the active snapshot locally and remove its external repository. Use ai details to inspect protection and the current story. Use workspace ls, history, fork, use, save, and reset to manage snapshots. The status output marks modified, untracked, added, deleted, renamed or copied, and conflicted paths with <M>, <U>, <A>, <D>, <R>, and <C>.

When ai init offers the external workspace choice, Create new recreates the external repository from local project copies, replacing its previous snapshot history. Restore existing recovers workspace files from the external repository's current worktree, including uncommitted changes, while preserving its branch and history. Initialization then creates any required workspace assets and reinstalls registered skills.

ai init and every successful ai workspace command ensure that .ai/plans, .ai/tasks, .ai/todos, .ai/skills, .ai/stories, .ai/temp, and .ai/rules exist, including after switching or resetting snapshots.

The mapping is stored in $HOME/.ai/workspaces.json, or in the file selected by AI_CLI_WS_CONFIG_FILE. Managed directories remain project-local copies on every platform and synchronize with the external repository through workspace commands.

Use --save-bundle or -b to copy successfully installed skills into .ai/skills. Those bundled copies are used only when reinstalling from the workspace registry without an explicit source. ai skills list shows skill names and flags; use --show-desc to include descriptions. ai skills list --bundle lists only bundled skills. Use ai skills show-install <name> to display the full install command for an installed skill. Run ai <command> --help for the complete syntax, including shell completion setup.

Stories

Run ai init before managing stories or checking ai details. Create a story with ai story new --name "My story". If no code is supplied, the next numeric code is allocated across active and archived directory names, starting at 001 and using at least three digits. Use --code (-c) for a custom code containing letters, digits, underscores, or hyphens; its first character must be a letter or digit, and archived is reserved. --name (-n) accepts a nonempty name. An interactive terminal prompts when the name is omitted.

Each story lives in .ai/stories/CODE/main.md, and creation selects it as the current story. Names are read from the first Markdown H1 outside fenced code, so editing that heading updates the displayed name. ai story ls lists active stories with Current or Idle status; --all includes Archived stories. The current code is stored in .ai/config.json as currentStory and shown by ai details.

ai story archive CODE moves a story into .ai/stories/archived/ and clears its selection if current. ai story unarchive [CODE] restores it without selecting it. Omitting CODE opens a picker containing only archived stories, with the first story focused. ai story use CODE selects a story, restoring it automatically if archived. Omitting CODE from archive, use, or rm opens a single-choice picker. Archive shows only active stories; use and rm show active stories followed by archived stories. Arrow keys change focus and Enter confirms directly; Escape cancels.

ai story rm CODE always asks for a second confirmation, defaulting to Cancel. Removing the current story clears its selection. Interactive selection and deletion require a terminal; noninteractive invocations needing those decisions fail. ai story patch creates the next patch-N.md in the current story and prints only its absolute path. Patch numbering advances past existing numeric patch files without overwriting them.

Shell Completion

Generate a completion script with ai completion generate <shell>. To print the configuration code for your shell profile without changing the profile, run ai completion config <shell>.

For Bash, add the output of the following command to ~/.bashrc:

ai completion config bash

For PowerShell, add the output of the following command to $PROFILE:

ai completion config powershell

License

This library is published under Apache-2.0 license.