mirror of
https://github.com/coleam00/Archon
synced 2026-04-21 21:47:53 +00:00
c142dbbc54
* feat(cli): Add git repository safety check Add validation to ensure CLI workflows only run from within a git repository. If the user runs from a subdirectory, the CLI resolves to the repo root. Running from a non-git directory produces a clear error message with guidance. - Add git.findRepoRoot() check before workflow commands - Bypass check for version/help commands - Add tests for git repo validation behavior * docs: Update CLI documentation for git repository requirement * fix(cli): Improve error handling and tests for git repo check - Move git.findRepoRoot() inside try-catch block to ensure proper error handling and database cleanup on unexpected errors - Add path existence validation before git check for clearer error messages - Improve tests: test real git.findRepoRoot behavior instead of mocks - Add tests for path validation and command categorization logic
159 lines
3.8 KiB
Markdown
159 lines
3.8 KiB
Markdown
# Archon CLI User Guide
|
|
|
|
Run AI-powered workflows from your terminal.
|
|
|
|
**For developers:** See [CLI Developer Guide](cli-developer-guide.md) for architecture and internals.
|
|
|
|
## Prerequisites
|
|
|
|
1. Clone the repository and install dependencies:
|
|
```bash
|
|
git clone https://github.com/dynamous-community/remote-coding-agent
|
|
cd remote-coding-agent
|
|
bun install
|
|
```
|
|
|
|
2. Make CLI globally available (recommended):
|
|
```bash
|
|
cd packages/cli
|
|
bun link
|
|
```
|
|
This creates an `archon` command available from anywhere.
|
|
|
|
3. Authenticate with Claude:
|
|
```bash
|
|
claude /login
|
|
```
|
|
|
|
**Note:** Examples below use `archon` (after `bun link`). If you skip step 2, use `bun run cli` from the repo directory instead.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# List available workflows (requires git repository)
|
|
archon workflow list --cwd /path/to/repo
|
|
|
|
# Run a workflow
|
|
archon workflow run assist --cwd /path/to/repo "Explain the authentication flow"
|
|
|
|
# Run in isolated worktree
|
|
archon workflow run plan --cwd /path/to/repo --branch feature-auth "Add OAuth support"
|
|
```
|
|
|
|
**Note:** Workflow and isolation commands require running from within a git repository. Running from subdirectories automatically resolves to the repo root. The `version` and `help` commands work anywhere.
|
|
|
|
## Commands
|
|
|
|
### `workflow list`
|
|
|
|
List workflows available in target directory.
|
|
|
|
```bash
|
|
archon workflow list --cwd /path/to/repo
|
|
```
|
|
|
|
Discovers workflows from `.archon/workflows/` (recursive) plus bundled defaults.
|
|
|
|
### `workflow run <name> [message]`
|
|
|
|
Run a workflow with an optional user message.
|
|
|
|
```bash
|
|
# Basic usage
|
|
archon workflow run assist --cwd /path/to/repo "What does this function do?"
|
|
|
|
# With isolation
|
|
archon workflow run plan --cwd /path/to/repo --branch feature-x "Add caching"
|
|
```
|
|
|
|
**Flags:**
|
|
|
|
| Flag | Effect |
|
|
|------|--------|
|
|
| `--cwd <path>` | Target directory (required for most use cases) |
|
|
| `--branch <name>` | Create/reuse worktree for branch |
|
|
| `--no-worktree` | Checkout branch directly (no worktree) |
|
|
|
|
**With `--branch`:**
|
|
- Creates worktree at `~/.archon/worktrees/<repo>/<branch>/`
|
|
- Reuses existing worktree if healthy
|
|
- Auto-registers codebase if in a git repo
|
|
|
|
**Without `--branch`:**
|
|
- Runs in target directory directly
|
|
- No isolation
|
|
|
|
### `isolation list`
|
|
|
|
Show all active worktree environments.
|
|
|
|
```bash
|
|
archon isolation list
|
|
```
|
|
|
|
Groups by codebase, shows branch, workflow type, platform, and days since activity.
|
|
|
|
### `isolation cleanup [days]`
|
|
|
|
Remove stale environments.
|
|
|
|
```bash
|
|
# Default: 7 days
|
|
archon isolation cleanup
|
|
|
|
# Custom threshold
|
|
archon isolation cleanup 14
|
|
```
|
|
|
|
### `version`
|
|
|
|
Show version, build type, and database info.
|
|
|
|
```bash
|
|
archon version
|
|
```
|
|
|
|
## Working Directory
|
|
|
|
The CLI determines where to run based on:
|
|
|
|
1. `--cwd` flag (if provided)
|
|
2. Current directory (default)
|
|
|
|
Running from a subdirectory (e.g., `/repo/packages/cli`) automatically resolves to the git repository root (e.g., `/repo`).
|
|
|
|
When using `--branch`, workflows run inside the worktree directory.
|
|
|
|
## Environment
|
|
|
|
The CLI loads environment from:
|
|
1. `.env` in current directory
|
|
2. `~/.archon/.env` (fallback)
|
|
|
|
Auto-enables global Claude auth if no explicit tokens are set.
|
|
|
|
## Database
|
|
|
|
- **With `DATABASE_URL`:** Uses PostgreSQL
|
|
- **Without:** Uses SQLite at `~/.archon/archon.db`
|
|
|
|
Both work transparently. SQLite is auto-initialized on first run.
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
# Quick question about code
|
|
archon workflow run assist --cwd ~/projects/my-app "How does error handling work here?"
|
|
|
|
# Plan a feature (no code changes)
|
|
archon workflow run plan --cwd ~/projects/my-app "Add rate limiting to the API"
|
|
|
|
# Implement on isolated branch
|
|
archon workflow run implement --cwd ~/projects/my-app --branch feature-rate-limit "Add rate limiting"
|
|
|
|
# Check worktrees after work session
|
|
archon isolation list
|
|
|
|
# Clean up old worktrees
|
|
archon isolation cleanup
|
|
```
|