npm package: @redredchen01/deploy-tools
Description: Deployment management CLI — deploy, rollback, promote, canary, status, history, config
Author: redredchen01
Latest version: 1.0.0

# @redredchen01/deploy-tools

> Deployment management CLI — deploy, rollback, promote, canary, status, history, config

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

## Install

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

## Quick Start

```bash
# Initialize deploy config
deploy-tools config init

# Edit .deployrc to set your environments
deploy-tools config set staging_target deploy@staging.example.com:/var/www/app
deploy-tools config set production_target deploy@prod.example.com:/var/www/app

# Deploy to staging
deploy-tools deploy --source ./dist --target deploy@staging.example.com:/var/www/app

# Check status
deploy-tools status

# Promote staging to production
deploy-tools promote

# View history
deploy-tools history
```

## Commands

### `deploy` — Deploy to remote server

Deploy a local directory to a remote server via rsync over SSH. Records each deployment to `.deploy-history`.

```bash
deploy-tools deploy --target deploy@myserver.com:/var/www/app
deploy-tools deploy --source ./dist --target user@host:/app --exclude node_modules
deploy-tools deploy --target user@host:/app --dry-run
deploy-tools deploy --target user@host:/app --exclude '*.log' --exclude '.git'
```

Options: `--source DIR`, `--target USER@HOST:PATH`, `--exclude PATTERN` (repeatable), `--dry-run`, `--env ENV`, `--json`

---

### `rollback` — Rollback to previous version

Rollback to a previous deployment by re-running rsync with the previously recorded source directory. Reads `.deploy-history`.

```bash
deploy-tools rollback --target deploy@myserver.com:/var/www/app
deploy-tools rollback --target user@host:/app --steps 2
deploy-tools rollback --target user@host:/app --env production
```

Options: `--target USER@HOST:PATH`, `--steps N`, `--env ENV`, `--dry-run`, `--json`

---

### `promote` — Promote environment

Promote one environment to another using targets configured in `.deployrc`. Requires triple confirmation for production unless `--force` is used.

```bash
deploy-tools promote
deploy-tools promote --from staging --to production
deploy-tools promote --config ./deploy/.deployrc --force  # CI usage
```

Options: `--from ENV`, `--to ENV`, `--config FILE`, `--force`, `--dry-run`, `--json`

---

### `canary` — Canary release

Deploy to a percentage of servers from a server list file (one `USER@HOST:PATH` per line).

```bash
deploy-tools canary --servers ./servers.txt
deploy-tools canary --source ./dist --servers ./servers.txt --percent 25
deploy-tools canary --servers ./servers.txt --percent 100 --dry-run
```

Options: `--source DIR`, `--servers FILE`, `--percent N`, `--dry-run`, `--json`

---

### `status` — Environment status

Show current deployment status for each environment defined in `.deployrc`, with last deploy timestamp.

```bash
deploy-tools status
deploy-tools status --config ./deploy/.deployrc
deploy-tools status --json
```

Options: `--config FILE`, `--json`

---

### `history` — Deployment history

Show deployment history from `.deploy-history` file.

```bash
deploy-tools history
deploy-tools history --limit 20
deploy-tools history --env production
deploy-tools history --env staging --limit 5 --json
```

Options: `--limit N`, `--env ENV`, `--json`

---

### `config` — Manage .deployrc

Manage the deploy configuration file.

```bash
deploy-tools config init                                      # create template
deploy-tools config show                                      # print config
deploy-tools config set staging_target user@host:/app         # set a key
deploy-tools config get staging_target                        # get a key
```

Subcommands: `init`, `show`, `set KEY VALUE`, `get KEY`

Options: `--config FILE`, `--json`

---

## Deploy Config (.deployrc)

```ini
# .deployrc — deploy-tools configuration
staging_target=deploy@staging.example.com:/var/www/app
staging_source=./dist

production_target=deploy@prod.example.com:/var/www/app
production_source=./dist
```

Create with: `deploy-tools config init`

## Deploy History (.deploy-history)

Each `deploy`, `rollback`, and `promote` appends a line to `.deploy-history`:

```
2026-03-17T10:00:00Z|staging|deploy@staging.example.com:/var/www/app|./dist|ok
2026-03-17T11:30:00Z|production|deploy@prod.example.com:/var/www/app|./dist|promote
```

Format: `TIMESTAMP|ENV|TARGET|SOURCE|RESULT`

## JSON Output (Pipe Protocol)

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

```bash
deploy-tools status --json | some-other-tool
deploy-tools history --env production --json | jq '.data.entries[]'
```

## Error Codes

- **E1** — Required tool not installed (rsync, ssh)
- **E2** — Connection failure (SSH/rsync error)
- **E3** — Permission denied on remote

## License

MIT