@moxxy/agent-cli

@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