npm package: @moxxy/agent-cli
Description: Agent-facing CLI tool for structured operations
Latest version: 0.0.12

# @moxxy/agent-cli

Agent-facing CLI tool for structured operations. Part of the [Moxxy](https://github.com/webeferen/moxxy) orchestration platform.

Designed to be invoked by AI agents rather than humans. All output is JSON-structured for reliable parsing, with execution timing on every command.

## Installation

```bash
npm install -g @moxxy/agent-cli
```

## Quick Start

```bash
# Clone and set up a workspace
moxxy-agent workspace init --repo https://github.com/owner/repo

# Read a file
moxxy-agent file read src/index.ts

# Search for a pattern
moxxy-agent search code "TODO|FIXME" --type ts

# Create a branch, make changes, commit, and open a PR
moxxy-agent git checkout -b fix/bug-123
moxxy-agent file patch src/app.ts --search "oldValue" --replace "newValue"
moxxy-agent git add --all
moxxy-agent git commit -m "fix: resolve bug 123"
moxxy-agent git push --set-upstream
moxxy-agent pr create --title "fix: resolve bug 123" --base main
```

## Structured Output

Every command returns a JSON `AgentCommandResult`:

```jsonc
// Success
{ "success": true, "command": "file read", "data": { ... }, "duration_ms": 12 }

// Failure
{ "success": false, "command": "file read", "error": { "code": "NOT_FOUND", "message": "..." }, "duration_ms": 3 }
```

## Commands

### Workspace

| Command | Description |
|---------|-------------|
| `workspace init --repo <url> [--branch <b>] [--clone-dir <p>]` | Clone repo and set up workspace |
| `workspace info` | Show workspace context (cwd, git, package manager) |
| `workspace clean <path>` | Remove workspace directory |

### File

| Command | Description |
|---------|-------------|
| `file create <path> --content <c>` | Create a new file |
| `file read <path> [--lines start:end]` | Read file contents |
| `file update <path> --content <c>` | Overwrite file contents |
| `file delete <path>` | Delete a file |
| `file move <source> <dest>` | Move or rename a file |
| `file patch <path> --search 
 --replace <r>` | Find-and-replace in a file |

Both `file create` and `file update` accept `--from-stdin` to read content from stdin.

### Directory

| Command | Description |
|---------|-------------|
| `dir list [path] [--recursive] [--pattern <glob>]` | List directory contents |
| `dir create <path>` | Create directory (with parents) |
| `dir delete <path>` | Remove directory |
| `dir tree [path] [--depth <n>]` | Display directory tree |

### Git

| Command | Description |
|---------|-------------|
| `git init [path]` | Initialize a repository |
| `git clone <url> [dir] [--branch <b>]` | Clone a repository |
| `git branch [name] [--list]` | Create or list branches |
| `git checkout <branch> [-b]` | Switch branches (optionally create) |
| `git add [files] [--all]` | Stage files |
| `git commit -m <message>` | Commit staged changes |
| `git push [--set-upstream] [--remote <r>] [--branch <b>]` | Push to remote |
| `git pull` | Pull from remote |
| `git diff [--staged]` | Show changes |
| `git status` | Show working tree status |
| `git log [--limit <n>]` | Show commit history |

### Search

| Command | Description |
|---------|-------------|
| `search code <query> [--path <dir>] [--type <ext>]` | Search for code patterns (regex) |
| `search files <pattern> [--path <dir>]` | Find files by glob pattern |
| `search docs <query> [--path <dir>]` | Search documentation files |

### Pull Requests

| Command | Description |
|---------|-------------|
| `pr create --title <t> [--body <b>] [--base <branch>]` | Create a pull request |
| `pr comment <number> --body <text>` | Comment on a pull request |

### Workflow

| Command | Description |
|---------|-------------|
| `workflow run <workflow-file>` | Run a workflow from a JSON definition |
| `workflow status` | Show status of running workflows |

### Global Options

| Flag | Description |
|------|-------------|
| `--cwd <path>` | Override working directory |
| `--verbose` | Enable verbose logging |

## Plugin Architecture

The CLI is built on a plugin system. Each built-in plugin (workspace, file, dir, git, search, pr, workflow) implements `IAgentPlugin` and registers its commands dynamically.

```typescript
import { PluginRegistry } from '@moxxy/agent-cli';
import type { IAgentPlugin } from '@moxxy/agent-cli';
```

## License

MIT