npm package: @redredchen01/ci-tools
Description: CI pipeline management CLI — init, lint-config, run-local, status, artifacts, cache, notify
Author: redredchen01
Latest version: 1.0.0

# @redredchen01/ci-tools

> CI pipeline management CLI — init, lint-config, run-local, status, artifacts, cache, notify

[![npm version](https://img.shields.io/npm/v/@redredchen01/ci-tools.svg)](https://www.npmjs.com/package/@redredchen01/ci-tools)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Install

```bash
npm install -g @redredchen01/ci-tools
```

## Quick Start

```bash
# Generate a CI config for the current project
ci-tools init

# Validate the generated config
ci-tools lint-config

# Simulate the pipeline locally
ci-tools run-local --dry-run

# Check recent run status
ci-tools status

# Download artifacts from the latest run
ci-tools artifacts --download
```

## Commands

### `init` — Generate CI config template

Auto-detects project language from `package.json`, `requirements.txt`, `go.mod`, or `Cargo.toml`.

```bash
ci-tools init
ci-tools init --platform github-actions --lang node
ci-tools init --platform gitlab-ci --lang python --output .gitlab-ci.yml
ci-tools init --platform circleci --lang go
```

Options: `--platform github-actions|gitlab-ci|circleci`, `--lang node|python|go|rust`, `--output FILE`, `--json`

---

### `lint-config` — Validate CI config syntax

Checks YAML structure, required keys, and common typos without requiring an external YAML parser.

```bash
ci-tools lint-config
ci-tools lint-config --file .github/workflows/ci.yml
```

Options: `--file FILE`, `--json`

---

### `run-local` — Simulate CI pipeline locally

Parses `run:` commands from CI config and executes them in your local shell.

```bash
ci-tools run-local
ci-tools run-local --step test
ci-tools run-local --dry-run
ci-tools run-local --file .github/workflows/ci.yml --step build
```

Options: `--file FILE`, `--step NAME`, `--dry-run`, `--json`

---

### `status` — Query GitHub Actions run status

Shows recent workflow runs with status indicators. Uses `gh` CLI if available, falls back to `curl` with `GITHUB_TOKEN`.

```bash
ci-tools status
ci-tools status --repo octocat/hello-world
ci-tools status --limit 10 --branch main
```

Options: `--repo OWNER/REPO`, `--limit N`, `--branch BRANCH`, `--json`

Environment: `GITHUB_TOKEN`

---

### `artifacts` — List or download CI artifacts

```bash
ci-tools artifacts --list
ci-tools artifacts --run-id 12345678 --download
ci-tools artifacts --run-id 12345678 --download --output ./ci-artifacts/
```

Options: `--repo OWNER/REPO`, `--run-id ID`, `--list`, `--download`, `--output DIR`, `--json`

Requires: `gh` CLI

---

### `cache` — Manage CI cache

```bash
ci-tools cache list
ci-tools cache size
ci-tools cache clear
ci-tools cache clear --key node-modules-abc123
```

Subcommands: `list`, `size`, `clear`

Options: `--repo OWNER/REPO`, `--key KEY`, `--json`

Requires: `gh` CLI

---

### `notify` — Send CI notifications

```bash
ci-tools notify --status pass
ci-tools notify --status fail --message "Tests failed on main"
ci-tools notify --status pass --webhook https://hooks.slack.com/services/...
```

Options: `--status pass|fail|error`, `--message MSG`, `--webhook URL`, `--stdout`, `--json`

Environment: `CI_NOTIFY_WEBHOOK`

---

## JSON Output (Pipe Protocol)

All commands support `--json` for structured output compatible with the Skill Foundry pipe protocol:

```bash
ci-tools status --json | some-other-tool
ci-tools artifacts --list --json | jq '.data.artifacts[].name'
```

## Requirements

| Command      | Required Tools              |
|--------------|-----------------------------|
| init         | bash 3.2+                   |
| lint-config  | bash 3.2+                   |
| run-local    | bash 3.2+                   |
| status       | gh CLI or curl + GITHUB_TOKEN |
| artifacts    | gh CLI                      |
| cache        | gh CLI                      |
| notify       | curl (for webhook delivery) |

## License

MIT