feat: Initial arr CLI.md + setup instructions

CLI.md

@@ -0,0 +1,123 @@
+# arr CLI
+
+`arr` is a CLI for stacked PRs using [jj](https://github.com/martinvonz/jj). It enables stacking changes on top of each other to keep you unblocked and your changes small, focused, and reviewable.
+
+## Installation
+
+### Prerequisites
+
+- [Bun](https://bun.sh/docs/installation)
+- [jj](https://martinvonz.github.io/jj/latest/install-and-setup/)
+
+### Install globally
+
+```bash
+pnpm --filter @array/cli run link
+```
+
+This makes the `arr` command available globally in your terminal.
+
+## Core Concepts
+
+### Stack
+
+A sequence of changes, each building off of its parent.
+
+```
+main <- "add API" <- "update frontend" <- "docs"
+```
+
+### Trunk
+
+The branch that stacks are merged into (e.g., `main`).
+
+### Change
+
+A jj commit/revision. Unlike git, jj tracks the working copy as a change automatically - no need to stage files.
+
+## Commands
+
+### Setup Commands
+
+| Command | Description |
+|---------|-------------|
+| `arr init` | Initialize arr in a git repository (sets up jj colocated mode) |
+| `arr auth` | Authenticate with GitHub |
+| `arr config` | Configure arr settings |
+| `arr exit` | Switch back to plain git (preserves jj changes) |
+
+### Core Workflow Commands
+
+| Command | Aliases | Description |
+|---------|---------|-------------|
+| `arr create <message>` | `c` | Save current changes as a new change with a description |
+| `arr submit` | `s` | Create or update PRs for the current stack |
+| `arr sync` | | Fetch from remote and rebase local changes |
+| `arr restack` | | Rebase the current stack onto its parent |
+| `arr merge` | | Merge approved PRs from the CLI |
+
+### Stack Navigation
+
+| Command | Aliases | Description |
+|---------|---------|-------------|
+| `arr up` | `u` | Move to the child change |
+| `arr down` | `d` | Move to the parent change |
+| `arr top` | | Move to the top of the stack |
+| `arr bottom` | `b` | Move to the bottom of the stack |
+| `arr trunk` | `t` | Move to the trunk branch |
+| `arr checkout <rev>` | `co` | Check out a specific change |
+
+### Stack Info
+
+| Command | Aliases | Description |
+|---------|---------|-------------|
+| `arr log` | `l` | Show a visual overview of the current stack with PR status |
+| `arr status` | `st` | Show the status of the current change |
+
+### Stack Management
+
+| Command | Description |
+|---------|-------------|
+| `arr get <pr>` | Fetch a PR and add it to the local stack |
+| `arr track <rev>` | Start tracking a change for PR submission |
+| `arr untrack <rev>` | Stop tracking a change |
+| `arr delete <rev>` | Delete a change |
+| `arr modify` | Edit the current change's description |
+| `arr resolve` | Mark conflicts as resolved |
+| `arr split` | Split the current change into multiple changes |
+| `arr squash` | Squash changes together |
+| `arr undo` | Undo the last operation |
+
+## Core Workflow
+
+1. **Make edits** - No need to stage, jj tracks automatically
+2. **Save as a change** - `arr create "add user model"`
+3. **Stack more work** - Make more edits
+4. **Save another change** - `arr create "add user api"`
+5. **Create PRs** - `arr submit` creates PRs for the entire stack
+6. **Merge PRs** - `arr merge` merges approved PRs from the CLI
+7. **Sync after reviews** - `arr sync` fetches and rebases
+
+## Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--help` | Show help for a command |
+| `--help --all` | Show full command reference |
+| `--version` | Show arr version number |
+| `--debug` | Show debug timing information |
+
+## Escape Hatch
+
+If you need to switch back to plain git:
+
+```bash
+arr exit
+```
+
+Your jj changes are preserved and you can return anytime by running `arr init` again.
+
+## Learn More
+
+- [jj documentation](https://martinvonz.github.io/jj/latest/)
+- [Array repository](https://github.com/posthog/array)

README.md

@@ -9,6 +9,7 @@ This is the monorepo for PostHog's Array desktop task manager and the agent fram
 ## Projects
 
 - **[apps/array](./apps/array)** - The Array desktop application
+- **[apps/cli](./apps/cli)** - The `arr` CLI for stacked PRs using jj
 - **[packages/agent](./packages/agent)** - The TypeScript agent framework
 
 ## Development
@@ -17,6 +18,8 @@ This is the monorepo for PostHog's Array desktop task manager and the agent fram
 
 - Node.js 22+
 - pnpm 10.23.0
+- [Bun](https://bun.sh/docs/installation) (for the CLI)
+- [jj](https://martinvonz.github.io/jj/latest/install-and-setup/) (for the CLI)
 
 ### Setup
 
@@ -31,6 +34,17 @@ pnpm install
 pnpm --filter agent build
 ```
 
+### Installing the CLI
+
+The CLI requires [Bun](https://bun.sh/docs/installation) and [jj](https://martinvonz.github.io/jj/latest/install-and-setup/).
+
+```bash
+# Install the arr CLI globally
+pnpm --filter @array/cli run link
+```
+
+See [CLI.md](./CLI.md) for detailed CLI documentation.
+
 ### Running in Development
 
 ```bash
@@ -63,7 +77,8 @@ pnpm test
 ```
 array-monorepo/
 ├── apps/
-│   └── array/          # Electron desktop app
+│   ├── array/          # Electron desktop app
+│   └── cli/            # arr CLI for stacked PRs
 ├── packages/
 │   └── agent/          # Agent framework
 ├── pnpm-workspace.yaml # Workspace configuration

apps/cli/package.json

@@ -9,6 +9,7 @@
   "scripts": {
     "build": "bun build ./src/cli.ts --outdir ./dist --target bun",
     "dev": "bun run ./bin/arr.ts",
+    "link": "bun link",
     "typecheck": "tsc --noEmit",
     "test:pty": "vitest run tests/e2e/pty.test.ts"
   },