npm package: @postqode/cli
Description: Command-line interface for Postqode API testing framework
Latest version: 0.1.42

# @postqode/cli

> A powerful command-line tool for running API test suites and converting API collection formats. Automate your API testing workflow with comprehensive reporting and format conversion capabilities.

---

## 🚀 Installation

Install globally via npm:

```bash
npm install -g @postqode/cli
```

Verify installation:

```bash
postqode-runner -V
```

---

## 📖 Usage

### Global Options

| Option | Description |
|--------|-------------|
| `-V, --version` | Output the CLI version |
| `-v, --verbose` | Enable verbose output for debugging |
| `-h, --help` | Display help information |

### Commands

#### Execute Test Suites

Run API test suites with comprehensive reporting options:

```bash
postqode-runner execute [options]
```

**Options:**

| Option | Description | Default |
|--------|-------------|---------|
| `-s, --suite <file>` | Test suite file path (e.g. `_meta.suite.yaml`) | Required |
| `-w, --workspace <dir>` | Workspace directory | Current project directory |
| `-c, --config <name>` | Run configuration name (profile for environment/settings) | Default |
| `--report-formats <formats>` | Report formats to generate (`html`, `junit`, `overview`) | `html` |
| `--report-dir <dir>` | Directory to save reports | Current directory |

**Examples:**

```bash
# Run a test suite with default HTML report
postqode-runner execute -s testSuites/MySuite/_meta.suite.yaml

# Run with multiple report formats
postqode-runner execute -s testSuites/MySuite/_meta.suite.yaml --report-formats html junit

# Run with custom workspace and report directory
postqode-runner execute -s testSuites/MySuite/_meta.suite.yaml -w /projects/myWorkspace --report-dir reports
```

#### Convert API Collections

Convert between OpenAPI, Postman Collections, and Postqode test formats:

```bash
postqode-runner convert [options]
```

**Options:**

| Option | Description | Example |
|--------|-------------|---------|
| `-i, --input <file>` | Input file or URL (OpenAPI, Postman) | `openapi.yaml` |
| `-o, --output <file>` | Output file | `collection.json` |

**Examples:**

```bash
# Convert OpenAPI to Postman Collection
postqode-runner convert -i openapi.yaml -o collection.json

# Convert Postman Collection to Postqode Test Suite
postqode-runner convert -i collection.json -o testSuites/MySuite/_meta.suite.yaml
```

---

## 📊 Reporting

The execute command supports multiple reporting formats:

- **HTML** → Human-readable execution summary with test results
- **JUnit** → XML format for CI/CD pipelines (Jenkins, GitLab, etc.)
- **Overview** → Minimal summary report for quick validation

Reports are saved in the `--report-dir` directory (default: current workspace).

---

## 🏗️ Example Workflow

1. **Convert OpenAPI to Test Suite:**
   ```bash
   postqode-runner convert -i openapi.yaml -o testSuites/MySuite/_meta.suite.yaml
   ```

2. **Execute test suite with reports:**
   ```bash
   postqode-runner execute -s testSuites/MySuite/_meta.suite.yaml --report-formats html junit
   ```

3. **Check generated reports** in the `/reports` directory

---

## 🎯 Best Practices

- ✅ Always use workspace (`-w`) to organize test suites
- ✅ Use run configurations (`-c`) for different environments (e.g. Dev, QA, Prod)
- ✅ Store test suites under `testSuites/` with `_meta.suite.yaml` as entry points
- ✅ Automate CLI execution inside CI/CD pipelines (e.g. Jenkins, GitHub Actions)

---

## 🔧 Troubleshooting

| Issue | Solution |
|-------|----------|
| Command not found | Ensure `@postqode/cli` is installed globally |
| Permission issues | Use `sudo npm install -g @postqode/cli` (Linux/macOS) |
| Invalid suite file | Verify `_meta.suite.yaml` structure |

---

## 🤝 Contributing

We welcome contributions! Please feel free to submit issues and pull requests.

---

## 📄 License

This project is licensed under the Apache License 2.0.

---

## 🆘 Support

For support and questions, please visit our documentation or create an issue in the repository.

---

**Keywords:** API testing, CLI tool, test automation, OpenAPI, Postman, test suites, CI/CD, reporting