@4ge/cli 0.1.0

package/usage.md

@@ -0,0 +1,320 @@
+# 4ge CLI Usage Guide
+
+> A Universal Interface for 4ge Resources
+
+## Installation & Setup
+
+### Prerequisites
+- Node.js >= 24
+
+### Install (end users)
+
+Install the published CLI globally from npm:
+
+```bash
+npm install -g @4ge/cli
+4ge --help
+```
+
+Requires Node.js 24+. The package ships prebuilt (`dist/` is built at publish
+time via CI), so no build step runs on your machine.
+
+Update later:
+```bash
+npm update -g @4ge/cli
+```
+
+### Install (contributors / from source)
+
+Clone and install dependencies:
+```bash
+git clone git@github.com:Conflate-AI/4ge-cli.git
+cd 4ge-cli
+pnpm install
+pnpm sync-api   # sync Zod schemas + API client from the Core API OpenAPI spec
+```
+
+### Run
+- **Production (installed)**: `4ge <command>`
+- **Development (from source)**: `pnpm dev <command>`
+- **Build only**: `pnpm build` (outputs `dist/`)
+
+## Quick Start
+
+1. **Install**: `npm install -g @4ge/cli`
+2. **Authenticate**: `4ge auth:login --token <your_api_key>`
+3. **Initialize a project**: `4ge init`
+4. **Check status**: `4ge whoami`
+5. **Install the agent skill** (optional): `4ge skill:install`
+
+
+## Authentication
+
+### Overview
+The 4ge CLI supports two primary authentication methods:
+- **PAT (Personal Access Token)**: For headless, CI/CD, or AI agent use via the `--token` flag or environment variables.
+- **OAuth (Future)**: Interactive browser-based login for human users (not yet available).
+
+### Credential Resolution Order
+The CLI resolves credentials in the following order of priority:
+1. `4GE_API_KEY` environment variable
+2. Local project configuration: `./.4ge/credentials.json`
+3. Global profile configuration: `~/.4ge/credentials.json` (active profile)
+
+### `4ge auth:login`
+Authenticate and save credentials to your preferred scope.
+
+```bash
+# Save to default global profile
+4ge auth:login --token <api_key>
+
+# Save to a specific named profile
+4ge auth:login --token <api_key> --profile work
+
+# Save to the current project (local override)
+4ge auth:login --token <api_key> --local
+```
+
+### `4ge auth:status` / `4ge whoami`
+Check the current authentication status and identify the active user.
+
+**Human Output:**
+```bash
+$ 4ge whoami
+Authenticated as: Matt (matt@example.com)
+Source: Local config (./.4ge/credentials.json)
+Workspace: 4ge-internal
+```
+
+**JSON Output:**
+```bash
+$ 4ge whoami --json
+{
+  "data": {
+    "authenticated": true,
+    "user": { "id": "uuid", "email": "matt@example.com", "name": "Matt" },
+    "source": "local",
+    "workspace": "4ge-internal"
+  },
+  "error": null,
+  "metadata": { "timestamp": "2026-05-23T10:00:00.000Z" }
+}
+```
+
+### `4ge auth:logout`
+Clear stored credentials from different scopes.
+
+```bash
+# Clear active global profile
+4ge auth:logout
+
+# Clear local project credentials
+4ge auth:logout --local
+
+# Clear a specific named profile
+4ge auth:logout --profile work
+```
+
+### Named Profiles
+Manage multiple environments or accounts using the profile system.
+
+- `4ge auth:profile:list` — List all stored profiles.
+- `4ge auth:profile:use <name>` — Switch the active global profile.
+- `4ge auth:profile:delete <name>` — Remove a profile from global storage.
+
+**Credential File Format (`~/.4ge/credentials.json`):**
+```json
+{
+  "activeProfile": "default",
+  "profiles": {
+    "default": {
+      "token": "4ge_pat_...",
+      "baseUrl": "http://localhost:3000"
+    },
+    "work": {
+      "token": "4ge_pat_...",
+      "baseUrl": "https://api.4ge.io"
+    }
+  }
+}
+```
+
+## Project Initialization
+
+### `4ge init`
+Sets up the current directory as a 4ge project. This is an interactive process:
+1. Validates authentication.
+2. Prompts for workspace selection.
+3. Prompts for project selection.
+4. Creates `.4ge/config.yaml`.
+5. Updates `.4ge/.gitignore` to exclude secrets.
+6. Offers to install the AI agent skill (default: No).
+
+**Non-interactive (JSON) mode:**
+To run `init` in automation, you must provide the workspace and project IDs:
+```bash
+4ge init --json --workspace <uuid> --project <uuid>
+```
+To auto-install the agent skill non-interactively, add `--skill`:
+```bash
+4ge init --json --workspace <uuid> --project <uuid> --skill
+```
+
+## Agent Skill
+
+The CLI ships an agent-facing skill document (`skills/4ge-cli.md` in the package)
+that teaches AI agents how to use the CLI. Install it into a project so your
+agent (pi, Cursor, Claude Code, Codex, etc.) picks it up automatically.
+
+Install mirrors the [`npx skills`](https://github.com/vercel-labs/skills)
+directory convention:
+
+```bash
+# Default: universal project scope -> .agents/skills/4ge-cli/SKILL.md
+4ge skill:install
+
+# Target a specific agent harness
+4ge skill:install --agent pi             # -> .pi/skills/4ge-cli/SKILL.md
+4ge skill:install --agent claude-code    # -> .claude/skills/4ge-cli/SKILL.md
+
+# Install to user (global) scope
+4ge skill:install --global
+
+# Overwrite an existing install
+4ge skill:install --force
+```
+
+Supported agents: `universal` (default, shared by Cursor/Cline/Codex/Gemini
+CLI/GitHub Copilot/OpenCode), `pi`, `claude-code`, `cursor`, `codex`,
+`gemini-cli`, `windsurf`, `continue`.
+
+`4ge init` also offers to install the skill on completion (prompt in pretty
+mode, or `--skill` flag for automation).
+
+### `.4ge/` Directory Structure
+```
+.4ge/
+├── config.yaml           # Project configuration (committed to git)
+├── credentials.json      # Local credential override (gitignored)
+└── .env                  # Environment overrides (gitignored)
+```
+
+### `.4ge/config.yaml` Reference
+The primary configuration file for project-specific behavior.
+
+```yaml
+project_id: "00000000-0000-0000-0000-000000000000"
+workspace_id: "11111111-1111-1111-1111-111111111111"
+project_name: "My Awesome Project"
+workspace_name: "Personal Workspace"
+hierarchy:
+  default_roadmap_filter: "now"     # now | next | later | all
+  recursive_pull: true
+pull:
+  generate_stubs: false
+  include_brief_deps: false
+```
+
+## JSON Mode (for AI Agents & Automation)
+
+### Overview
+Use the `--json` flag for deterministic, machine-readable output.
+- Suppresses all interactive prompts (TUI/Ink).
+- Outputs a standardized JSON envelope to `stdout`.
+- Sends `X-Client-Type: 4ge-agent` header to the API.
+
+### JSON Envelope Structure
+Every successful command returns:
+```json
+{
+  "data": { ... },
+  "error": null,
+  "metadata": {
+    "timestamp": "2026-05-23T10:00:00.000Z"
+  }
+}
+```
+
+### Error Envelope
+When a command fails in `--json` mode:
+```json
+{
+  "data": null,
+  "error": {
+    "message": "Not authenticated",
+    "code": "NO_CREDENTIALS"
+  },
+  "metadata": {
+    "timestamp": "2026-05-23T10:00:00.000Z"
+  }
+}
+```
+
+### Error Codes
+- `NO_CREDENTIALS` — No authentication found in any scope.
+- `ALREADY_INITIALIZED` — Project already contains `.4ge/config.yaml`.
+- `MISSING_REQUIRED_FLAGS` — Required flags (like `--workspace`) missing in `--json` mode.
+- `INVALID_TOKEN` — Token validation against the API failed.
+- `PROFILE_NOT_FOUND` — The specified named profile does not exist.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `4GE_API_KEY` | API key for headless auth (highest priority). |
+| `4GE_API_URL` | Override base API URL (default: `http://localhost:3000`). |
+
+## Security
+
+### Credential Storage
+- **Global credentials**: `~/.4ge/credentials.json` (saved with mode `0o600`).
+- **Local credentials**: `./.4ge/credentials.json` (saved with mode `0o600`).
+- **Config directories**: Config directories are created with mode `0o700`.
+- **Git Safety**: `4ge init` automatically adds `.4ge/credentials.json` and `.4ge/.env` to your `.gitignore`.
+
+### Best Practices
+- Use `4GE_API_KEY` environment variables for CI/CD environments.
+- Use named profiles for switching between different 4ge workspaces/accounts.
+- Use `--local` for project-specific credentials if you are collaborating on a shared machine.
+- **Never commit `credentials.json` or `.env` to version control.**
+
+## Command Reference
+
+All commands support `--json` (machine output), `--dry-run` (mutations),
+`--retry <n>` (transient failures). Pull commands support `--recursive`,
+`--roadmap`, `--status`, `--save`, `--stdout`. Run `<command> --help` for
+full flag details.
+
+| Namespace | Commands |
+|-----------|----------|
+| `init` | Initialize a project (offers agent skill install) |
+| `whoami` / `auth:status` | Current auth status |
+| `auth:login` / `auth:logout` | Authenticate / clear credentials |
+| `auth:profile:list` / `:use` / `:delete` | Manage named profiles |
+| `project` | `create` `info` `list` `pull` `update` |
+| `epic` | `list` `show` `pull` `update` |
+| `story` | `list` `show` `pull` `update` |
+| `feature` | `list` `show` `pull` `update` |
+| `idea` | `create` `graduate` `list` `show` `update` |
+| `plan` | `pull` `versions` |
+| `template` | `create` `delete` `info` `list` `pull` `update` |
+| `template:feature` | `create` `delete` `list` `update` |
+| `config` | `set` `get` `show` `manage` |
+| `skill` | `install` — install the agent skill for an AI harness |
+
+> `flow:*` commands are planned (not yet shipped).
+
+
+## Troubleshooting
+
+### "Not authenticated" error
+**Solution**: Run `4ge auth:login --token <api_key>` or set the `4GE_API_KEY` environment variable.
+
+### "Already initialized" error
+**Solution**: Edit `.4ge/config.yaml` directly if you need to change settings, or delete it and re-run `4ge init`.
+
+### "Module not found" warnings in dev mode
+**Explanation**: When running in `pnpm dev` mode, oclif v4 may emit `SINGLE_COMMAND_CLI` or loader warnings. These are harmless and do not affect functionality.
+
+### Token validation fails but credentials are saved
+**Explanation**: The CLI attempts to validate tokens against the API during login. If the API is unreachable (e.g., local dev server is down), credentials are still saved as a graceful fallback. Check your `4GE_API_URL` and network connection.