ward-cli 0.2.0

GitHub repository management for developers. Plan, apply, verify.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

<div align="center">

<pre>
 _ _ _  ___  ___  ___
| | | || . || . \| . \
| | | ||   ||   /| | |
|__/_/ |_|_||_\_\|___/
</pre>

**GitHub repository management as infrastructure-as-code.**

[![Rust](https://img.shields.io/badge/Rust-CC5500?style=flat-square&logo=rust&logoColor=FFBF00&labelColor=1C1C1C)](https://rust-lang.org)
[![License](https://img.shields.io/badge/License-MIT-6B8E23?style=flat-square&labelColor=1C1C1C)](LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/OriginalMHV/ward/ci.yml?style=flat-square&label=CI&labelColor=1C1C1C&color=6B8E23)](https://github.com/OriginalMHV/Ward/actions)
[![Crates.io](https://img.shields.io/crates/v/ward-cli?style=flat-square&labelColor=1C1C1C&color=6B8E23)](https://crates.io/crates/ward-cli)

[Install](#install) · [Quick Start](#quick-start) · [Docs](#documentation) · [Contributing](CONTRIBUTING.md)

</div>

────────────────────────────────────────

## What is Ward?

Ward is a Rust CLI that treats GitHub repository management as infrastructure-as-code. Declare your desired state in `ward.toml`, diff it against reality, apply changes, and verify the result. No shell scripts, no cloning, no guessing.

## Install

```bash
# from crates.io (recommended)
cargo install ward-cli

# homebrew (macOS / Linux)
brew install OriginalMHV/tap/ward-cli

# shell script (macOS / Linux)
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/OriginalMHV/Ward/releases/latest/download/ward-cli-installer.sh | sh

# powershell (Windows)
powershell -ExecutionPolicy ByPass -c "irm https://github.com/OriginalMHV/Ward/releases/latest/download/ward-cli-installer.ps1 | iex"

# from source
git clone https://github.com/OriginalMHV/Ward.git
cd Ward && cargo install --path .
```

Requires Rust >= 1.85 (source install only) and a GitHub token (`GH_TOKEN`, `GITHUB_TOKEN`, or `gh auth token`).
Token scopes needed: `repo`, `read:org`, `workflow`.

<details>
<summary><b>Shell completions</b></summary>

```bash
ward completions bash > ~/.bash_completion.d/ward
ward completions zsh  > ~/.zfunc/_ward
ward completions fish > ~/.config/fish/completions/ward.fish
```

</details>

## Quick Start

```bash
ward init                               # interactive setup wizard
vim ward.toml                           # review and adjust config
ward repos list --system backend        # see what's out there
ward security plan --system backend     # dry-run: what would change?
ward security apply --system backend    # apply + auto-verify
```

Use `ward init --non-interactive` to scaffold a minimal `ward.toml` without the wizard.

## Documentation

| Guide | Description |
|-------|-------------|
| [Configuration](docs/configuration.md) | `ward.toml` format, systems, overrides |
| [Commands](docs/commands.md) | Full CLI reference |
| [Templates](docs/templates.md) | Built-in and custom Tera templates |
| [TUI Dashboard](docs/tui.md) | Interactive terminal interface |
| [CI Integration](docs/ci-integration.md) | Using Ward in GitHub Actions |
| [Architecture](docs/architecture.md) | How Ward works under the hood |

## How it works

```
  Plan (read)  →  Apply (write)  →  Verify (read)

  Diff current    Execute with       Re-read from API,
  vs desired      audit logging      confirm match
```

- **No git cloning** -- file commits use the Git Trees API (blob, tree, commit, update ref). Atomic, no filesystem side effects.
- **Idempotent** -- detects existing state and skips what's already done.
- **Audit log** -- every mutation logged to `~/.ward/audit.log` as JSON lines. Query with `jq`.
- **Custom templates** -- place `.tera` files in `~/.ward/templates/` to add or override built-in templates. Uses [Tera](https://keats.github.io/tera/) (Jinja2-compatible).

────────────────────────────────────────

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and workflow details.

```bash
cargo fmt && cargo clippy --tests -- -D warnings && cargo test
```

## License

MIT. See [LICENSE](LICENSE).