@moxxy/agent-cli

Agent-facing CLI tool for structured operations. Part of the 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

npm install -g @moxxy/agent-cli

Quick Start

# 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:

// 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 <s> --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.

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

License

MIT