@shipworthy/anchor-cli

Command-line interface for the Anchor project.

$ anchor <command> [options]

Install

Local development (inside repo)

# From repo root
yarn build         # compile packages
# or run directly in ts-node during dev

# Execute via the helper script
yarn anchor --help

Global install (coming with first npm release)

npm i -g @shipworthy/anchor-cli
anchor --help

The CLI bundles @shipworthy/anchor so you only need the single package globally.

Commands

| Command | Description | |---------|-------------| | anchor save [name] | Capture the current window layout (auto-names if omitted) | | anchor list [--all] | List saved layouts (filtered to current monitors unless --all) | | anchor restore <name> | Restore a previously saved layout │ | anchor remove <name> | Delete a layout from disk │ | anchor permissions | Check and grant macOS accessibility permissions |

Run anchor <command> --help for per-command flags.

macOS Permissions

Anchor requires accessibility permissions to control window positions on macOS:

# Check if permissions are granted
anchor permissions --check

# Prompt to grant permissions (opens System Preferences)
anchor permissions

The CLI will automatically prompt for permissions when needed during save, restore, or list --current commands.

Examples

Save the current layout with an automatic name:

anchor save

Save with a custom name:

anchor save "dual-monitor-work"

List layouts that match the current monitor setup:

anchor list

Force listing all layouts regardless of monitor configuration:

anchor list --all

How it works (high-level)

1. Delegates to the SDK (@shipworthy/anchor) for all logic.
2. Persists JSON snapshots under ~/.anchor/states.
3. Uses AppleScript (osascript) to query and move windows (Phase 1).
4. Will optionally load a native addon for improved speed in Phase 2.

Development

# Watch-mode build (all packages)
yarn dev

# Run the built CLI
node packages/cli/dist/index.js --help

Unit tests for core logic live in packages/core. The CLI currently has lightweight e2e tests planned for macOS CI runners.

License

MIT