---
name: zentao-cli
description: A modern CLI interface for ZenTao Project Management System with support for one-shot commands, REPL mode, and JSON output
version: 0.3.0
author: CLI-Anything
tags:
  - project-management
  - cli
  - zentao
  - task-management
  - bug-tracking
  - automation
command_groups:
  - name: auth
    description: Authentication commands
    commands:
      - login
      - logout
      - status
  - name: project
    description: Project management commands
    commands:
      - list
      - show
      - create
      - update
      - delete
  - name: task
    description: Task management commands
    commands:
      - list
      - show
      - create
      - assign
      - start
      - finish
      - close
  - name: bug
    description: Bug management commands
    commands:
      - list
      - show
      - create
      - assign
      - resolve
      - close
  - name: story
    description: Story/requirement management commands
    commands:
      - list
      - show
      - create
      - close
  - name: product
    description: Product management commands
    commands:
      - list
      - show
  - name: execution
    description: Execution (sprint) management commands
    commands:
      - list
      - show
  - name: user
    description: User management commands
    commands:
      - list
      - me
---

# ZenTao PMS CLI

A modern CLI interface for ZenTao Project Management System that enables efficient project, task, bug, and story management from the command line.

## Installation

```bash
pip install zentao-cli
```

## Quick Start

### 1. Authenticate

```bash
zentao-cli auth login --url http://zentao.example.com --account admin --password your_password
```

### 2. Use Commands

```bash
# List projects
zentao-cli project list

# Show project details
zentao-cli project show 123

# Create and manage tasks
zentao-cli task create --execution 123 --name "Implement feature" --assigned user1
zentao-cli task start 456
zentao-cli task finish 456

# JSON output for automation
zentao-cli project list --json
```

### 3. Interactive Mode

```bash
zentao-cli repl
```

## Command Reference

### Authentication (`auth`)

| Command | Description | Example |
|---------|-------------|---------|
| `login` | Login to ZenTao server | `auth login --url http://... --account admin --password pass` |
| `logout` | Logout from server | `auth logout` |
| `status` | Show auth status | `auth status` |

### Projects (`project`)

| Command | Description | Example |
|---------|-------------|---------|
| `list` | List all projects | `project list --status doing` |
| `show` | Show project details | `project show 123 --fields team,products` |
| `create` | Create new project | `project create --name "New Project" --begin 2024-01-01 --end 2024-03-31` |
| `update` | Update project | `project update 123 --name "Updated Name"` |
| `delete` | Delete project | `project delete 123` |

### Tasks (`task`)

| Command | Description | Example |
|---------|-------------|---------|
| `list` | List tasks | `task list --execution 123 --status doing` |
| `show` | Show task details | `task show 456` |
| `create` | Create new task | `task create --execution 123 --name "Task name" --assigned user1` |
| `assign` | Assign task | `task assign 456 --assigned user2` |
| `start` | Start task | `task start 456` |
| `finish` | Finish task | `task finish 456 --consumed 8` |
| `close` | Close task | `task close 456` |

### Bugs (`bug`)

| Command | Description | Example |
|---------|-------------|---------|
| `list` | List bugs | `bug list --product 123 --status active` |
| `show` | Show bug details | `bug show 789` |
| `create` | Create new bug | `bug create --title "Bug title" --product 123` |
| `resolve` | Resolve bug | `bug resolve 789 --resolution fixed` |
| `close` | Close bug | `bug close 789` |

### Stories (`story`)

| Command | Description | Example |
|---------|-------------|---------|
| `list` | List stories | `story list --product 123` |
| `show` | Show story details | `story show 100` |
| `create` | Create new story | `story create --title "Feature request" --product 123` |
| `close` | Close story | `story close 100` |

### Products (`product`)

| Command | Description | Example |
|---------|-------------|---------|
| `list` | List products | `product list` |
| `show` | Show product details | `product show 123` |

### Executions (`execution`)

| Command | Description | Example |
|---------|-------------|---------|
| `list` | List executions/sprints | `execution list --project 123` |
| `show` | Show execution details | `execution show 456` |

### Users (`user`)

| Command | Description | Example |
|---------|-------------|---------|
| `list` | List users | `user list` |
| `me` | Show current user | `user me` |

## Global Options

| Option | Description |
|--------|-------------|
| `--json` | Output in JSON format (for automation) |
| `--version` | Show version |
| `--help` | Show help |

## JSON Output

All commands support `--json` flag for machine-readable output:

```bash
zentao-cli project list --json
zentao-cli task show 456 --json
zentao-cli bug list --json
```

## REPL Mode

Interactive mode for multiple commands:

```bash
$ zentao-cli repl
zentao> auth login http://zentao.example.com admin password
zentao> project list
zentao> task create --execution 123 --name "Task" --assigned user1
zentao> exit
```

## Agent Usage Guidelines

When using this CLI from an AI agent:

1. **Always check authentication first**: Use `auth status` before other commands
2. **Use JSON output**: Add `--json` flag for reliable parsing
3. **Handle errors gracefully**: Check return codes and error messages
4. **Session persistence**: Authentication persists across invocations
5. **Batch operations**: Use REPL mode for multiple related operations

### Example Agent Workflow

```python
# Check auth status
result = subprocess.run(["zentao-cli", "auth", "status"], capture_output=True)
if "Not authenticated" in result.stdout:
    # Login
    subprocess.run(["zentao-cli", "auth", "login",
                   "--url", url, "--account", account, "--password", password])

# Get project list in JSON
result = subprocess.run(["zentao-cli", "project", "list", "--json"],
                       capture_output=True, text=True)
projects = json.loads(result.stdout)

# Create task
subprocess.run(["zentao-cli", "task", "create",
               "--execution", str(exec_id),
               "--name", task_name,
               "--assigned", assignee])
```

## Configuration

- Session stored in: `~/.config/zentao-cli/session.json`
- REPL history: `~/.config/zentao-cli/repl_history`

## Requirements

- Python 3.8+
- ZenTao PMS 18.0+ (for API v1)

## License

This CLI harness is provided for interfacing with ZenTao PMS.