@async/cli

@async/cli

Filesystem-routed commands for local projects and user-global tools.

@async/cli treats command directories as the CLI surface. A command such as:

cli gh pull

maps to a command directory like:

.cli/gh/pull/script.ts

The v1 contract is defined in SPEC.md. The package implements local and

user-global command discovery, command resolution, script execution,

machine-readable listing, --which, --new, --mv, context-file pointers,

help, command copy, and version output.

Install

pnpm add -D @async/cli

Binaries

The package declares two equivalent binaries:

cli
async-cli

Command Roots

cli discovers local .cli/ overlays from the current working directory upward

to the nearest Git root, then appends the user-global command tree. Use

ASYNC_CLI_GLOBAL_ROOT to replace the user-global tree and

ASYNC_CLI_PROJECT_ROOT to pin project-root behavior in tests or controlled

launchers.

Built-Ins

cli help
cli help gh
cli --list
cli --list --json
cli --which gh pull
cli --new gh pr
cli --new gh pr --root
cli --cp gh pull
cli --cp gh pull --to local
cli --mv gh pull
cli --mv gh pull --to local
cli --agents
cli --agents --write
cli --agents --check
cli --agents --claude --write
cli --version

Command scripts run from the caller's original working directory. .js and

.mjs scripts run directly with Node; .ts and .mts scripts use Node 24

native type stripping.

Use --cp to clone a command directory between local and user-global command

trees without removing the source. Use --mv when the source should be

transferred instead.

Development

pnpm run build
pnpm test
pnpm run pack:check
pnpm run release:check

Maintainers who want the shell to prefer this checkout over an npm-installed

copy can link the local binaries:

pnpm run local:link
pnpm run local:status
pnpm run local:unlink