npm package: @manet/agent-cli
Description: A flexible Agent CLI framework for building multimodal agent applications
Latest version: 0.0.4

# MANET Agent CLI

A flexible Agent CLI framework built on top of the **Agent Kernel** ([`@manet/agent`](https://www.npmjs.com/package/@manet/agent)). Deploy and run agents with ease, featuring built-in Web UI and powerful extensibility.

## Quick Start

### Installation

```bash
npm install @manet/agent-cli
```

### Basic Usage

```bash
# Start interactive Web UI (default)
manet

# Run with built-in agents
manet run sailors  # Agent Sailors
manet run omni-tars   # Omni-TARS
manet run mcp-agent   # MCP Agent

# Run with custom agent
manet run ./my-agent.js

# Start headless API server
manet serve

# Headless mode with direct input
manet --headless --input "Analyze current directory structure"

# Pipeline input
echo "Summarize this code" | manet --headless
```

## Built-in Agents

manet CLI includes several built-in agents:

- **`sailors`** - Agent Sailors: Advanced task automation and reasoning system
- **`omni-tars`** - Omni-TARS: Multi-modal agent with comprehensive capabilities
- **`mcp-agent`** - MCP Agent: Model Context Protocol agent for tool integration

```bash
# Use built-in agents
manet run sailors
manet run omni-tars
manet run mcp-agent
```

## Core Commands

### `manet` / `manet run`

Launches **interactive Web UI** for real-time conversation and file browsing.

```bash
manet run --port 8888 --open
manet run sailors --port 8888
manet run ./my-agent.js --port 8888
```

### `manet serve`

Starts **headless API server** for system integration.

```bash
manet serve --port 8888
# API available at: http://localhost:8888/api/v1/
```

### `manet run --headless`

**Silent mode** execution with stdout output, perfect for scripting.

```bash
# Text output (default)
manet run --headless --input "Analyze files" --format text

# JSON output
manet run --headless --input "Analyze files" --format json

# Include debug logs
manet run --headless --input "Analyze files" --include-logs
```

### `manet request`

Direct **LLM requests** for debugging and testing.

```bash
manet request --provider openai --model gpt-4 --body '{"messages":[{"role":"user","content":"Hello"}]}'
```

### `manet workspace`

**Workspace management** utilities.

```bash
manet workspace --init     # Initialize workspace
manet workspace --open     # Open in VSCode
manet workspace --status   # Show status
```

## Configuration

### Config Files

Supports multiple formats with auto-discovery of `manet.config.{ts,yaml,json}`:

```typescript
// manet.config.ts
import { AgentAppConfig } from '@manet/interface';

const config: AgentAppConfig = {
  model: {
    provider: 'openai',
    id: 'gpt-4',
    apiKey: process.env.OPENAI_API_KEY,
  },
  workspace: './workspace',
  server: { port: 8888 },
};

export default config;
```

### CLI Options

```bash
# Model configuration
manet --model.provider openai --model.id gpt-4 --model.apiKey sk-xxx

# Server settings
manet serve --port 3000

# Workspace path
manet --workspace ./my-workspace

# Debug mode
manet --debug
```

### Priority Order

1. **CLI arguments** (highest)
2. **Workspace config**
3. **User config file** (`--config`)
4. **Remote config URL**
5. **Default config** (lowest)

## Custom Development

_Coming soon_

## Advanced Features

### Event System

Built on **event-driven architecture** for monitoring agent execution:

```typescript
const eventStream = agent.getEventStream();

// Subscribe to all events
eventStream.subscribe((event) => {
  console.log('Event:', event.type, event);
});

// Subscribe to specific event types
eventStream.subscribeToTypes(['tool_call', 'tool_result'], (event) => {
  console.log('Tool event:', event);
});
```

### Console Interception

Capture and process console output during execution:

```typescript
import { ConsoleInterceptor } from '@manet/agent-cli';

const { result, logs } = await ConsoleInterceptor.run(
  async () => {
    return await agent.run('input');
  },
  {
    silent: true, // Suppress output
    capture: true, // Capture logs
  },
);
```

### Tool & MCP Server Filtering

Filter available tools and **MCP servers** via configuration:

```typescript
// In config
const config = {
  tool: {
    include: ['file_*', 'web_*'],
    exclude: ['dangerous_*'],
  },
  mcpServer: {
    include: ['filesystem', 'browser'],
    exclude: ['experimental_*'],
  },
};
```

```bash
# Via CLI
manet --tool.include "file_*,web_*" --tool.exclude "dangerous_*"
manet --mcpServer.include "filesystem" --mcpServer.exclude "experimental_*"
```

## API Reference

Refer to TypeScript definitions:

- [`@manet/agent-interface`](https://www.npmjs.com/package/@manet/agent-interface) - Core agent interfaces
- [`@manet/interface`](https://www.npmjs.com/package/@manet/interface) - Application layer interfaces
- [`@manet/agent-cli`](https://www.npmjs.com/package/@manet/agent-cli) - CLI framework interfaces

## Examples

<!-- TODO: Add screenshot placeholders for:
- Web UI interface
- CLI output examples
- Configuration file examples
-->

_[Placeholder: Add screenshots of Web UI interface and CLI usage examples]_

## Contributing

Welcome to submit issues and pull requests!

1. Follow existing code style
2. Add necessary test cases
3. Update relevant documentation

## License

Apache-2.0 License