Skip to content

docs(project): add stackctl CLI agent skill #49

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wax911 merged 1 commit into from
Jul 30, 2026
Merged

docs(project): add stackctl CLI agent skill #49

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 51 additions & 34 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,30 +2,31 @@

[![CI](https://github.com/AniTrend/stackctl/actions/workflows/ci.yml/badge.svg)](https://github.com/AniTrend/stackctl/actions/workflows/ci.yml)

A Deno-powered CLI for managing local Docker Compose stacks across multi-service repositories, with config-driven profiles, overrides, secrets, and render pipelines.
A Deno-powered CLI for managing local Docker Compose stacks across multi-service repositories, with
config-driven profiles, overrides, secrets, and render pipelines.

Status: **Active development** -- 14 of 15 commands implemented (see table below).
Status: **Active development** -- 14 top-level commands implemented (see table below).

---

## Commands

| Command | Status | Description |
|---|---|---|
| `stackctl init` | Implemented | Generate commented `.stackctl` config |
| `stackctl generate` | Implemented | Generate `stacks/*.yml` from per-service sources |
| `stackctl render` | Implemented | Resolve `${VAR}` placeholders in stack files |
| `stackctl up` | Implemented | Deploy stacks to Docker Swarm |
| `stackctl down` | Implemented | Tear down stacks |
| `stackctl status` | Implemented | Show service status |
| `stackctl logs` | Implemented | Follow service logs |
| `stackctl sync` | Implemented | Validate generated stacks match committed files (CI drift detection) |
| `stackctl doctor` | Implemented | Check system and project health |
| `stackctl reload` | Implemented | Re-render and reconcile without teardown |
| `stackctl secrets` | Implemented | Encrypt/decrypt/deploy/clean/check with SOPS+age |
| `stackctl env` | Implemented | Scaffold `.env` files from examples |
| `stackctl plan` | Implemented | Dry-run summary of all operations |
| `stackctl completions` | Implemented | Generate shell completions (bash/zsh/fish) |
| Command | Status | Description |
| ---------------------- | ----------- | -------------------------------------------------------------------- |
| `stackctl init` | Implemented | Generate commented `.stackctl` config |
| `stackctl generate` | Implemented | Generate `stacks/*.yml` from per-service sources |
| `stackctl render` | Implemented | Resolve `${VAR}` placeholders in stack files |
| `stackctl up` | Implemented | Deploy stacks to Docker Swarm |
| `stackctl down` | Implemented | Tear down stacks |
| `stackctl status` | Implemented | Show service status |
| `stackctl logs` | Implemented | Follow service logs |
| `stackctl sync` | Implemented | Validate generated stacks match committed files (CI drift detection) |
| `stackctl doctor` | Implemented | Check system and project health |
| `stackctl reload` | Implemented | Re-render and reconcile without teardown |
| `stackctl secrets` | Implemented | Encrypt/decrypt/deploy/clean/check with SOPS+age |
| `stackctl env` | Implemented | Scaffold `.env` files from examples |
| `stackctl plan` | Implemented | Dry-run summary of all operations |
| `stackctl completions` | Implemented | Generate shell completions (bash/zsh/fish) |

Override merging is integrated into `generate`, `render`, and `up` via the `--override` flag.

Expand All @@ -45,14 +46,15 @@ stackctl init
stackctl generate

# See what would happen
stackctl plan
stackctl plan all
```

---

## Features

- Config-driven profiles with layered overrides (`.stackctl`, `.stackctl.<profile>`, `.stackctl.local`)
- Config-driven profiles with layered overrides (`.stackctl`, `.stackctl.<profile>`,
`.stackctl.local`)
- SOPS + age encrypted secrets management
- `${VAR}` render pipeline with service-local env resolution
- Docker Swarm deploy with dry-run planning
Expand All @@ -61,23 +63,38 @@ stackctl plan

### Secrets Subcommands

| Subcommand | Description |
|---|---|
| `encrypt` | Encrypt `.env` files using SOPS + age |
| `decrypt` | Decrypt `.env.enc` files back to plaintext |
| `deploy` | Decrypt env files and deploy stacks |
| `clean` | Remove decrypted `.env` files securely (shred + rm) |
| `check` | Check secrets tooling availability (sops, age) |
| Subcommand | Description |
| ---------- | --------------------------------------------------- |
| `encrypt` | Encrypt `.env` files using SOPS + age |
| `decrypt` | Decrypt `.env.enc` files back to plaintext |
| `deploy` | Decrypt env files and deploy stacks |
| `clean` | Remove decrypted `.env` files securely (shred + rm) |
| `check` | Check secrets tooling availability (sops, age) |

### Env Subcommands

| Subcommand | Description |
|---|---|
| `list` | List `.env` files with status (present/missing/outdated) |
| `create` | Create `.env` from `.env.example` |
| `diff` | Compare `.env` against `.env.example` |
| `materialize` | Copy profile-specific env to `.env` |
| `audit` | Check for plaintext `.env` files with encrypted counterparts |
| Subcommand | Description |
| ------------- | ------------------------------------------------------------ |
| `list` | List `.env` files with status (present/missing/outdated) |
| `create` | Create `.env` from `.env.example` |
| `diff` | Compare `.env` against `.env.example` |
| `materialize` | Copy profile-specific env to `.env` |
| `audit` | Check for plaintext `.env` files with encrypted counterparts |

## AI agent skill

Agents can install the `stackctl-cli` skill for source-valid stackctl CLI guidance:

```bash
npx skills add anitrend/stackctl --skill stackctl-cli
npx skills add anitrend/stackctl --skill stackctl-cli -g -y
```

This installs only the AI agent skill. It does not install the `stackctl` CLI, add runtime
dependencies, or make this repository a Node or npm project. `stackctl` remains a Deno 2.x project
with dependencies resolved from JSR.

Restart or reload OpenCode after installing new skills so the skill is discovered.

## GitHub Actions

Expand Down
41 changes: 41 additions & 0 deletions skills/stackctl-cli/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
---
name: stackctl-cli
description: Use this skill when helping agents answer stackctl CLI usage questions, choose source-valid stackctl commands, or avoid stale documented examples.
---

# stackctl CLI

Use this skill when a task involves the `stackctl` command line interface, its install context,
command behavior, flags, examples, or agent-facing guidance.

## Ground rules

- Treat `src/cli/mod.ts` as authoritative for commands, arguments, flags, and behavior.
- If a command, flag, install mode, workflow, or Homebrew behavior is not verified in source or
accepted research, say it is unknown or check the source.
- Do not invent aliases, planned commands, positional arguments, deployment workflows, or Homebrew
post-install behavior.
- This is a Deno 2.x project published as `@anitrend/stackctl`. Do not treat it as a Node or npm
project.

## Hard CLI facts

- `sync` is drift validation only. Do not describe it as deploy.
- Do not show bare `stackctl plan`. Use an operation such as `stackctl plan all` or
`stackctl plan up`.
- `up` and `down` select stacks with `--stacks`, not positional stack names.
- `secrets deploy` accepts positional stack names.
- `logs` accepts positional service names and also supports `--stacks`.
- `doctor --fix-volumes` currently reports a stub check, not an implemented repair.
- Homebrew post-install messaging is not implemented in this repository.

## Quick command map

- Setup and generation: `init`, `generate`, `render`, `plan <operation>`.
- Stack lifecycle: `up`, `down`, `reload`, `status`, `logs`, `sync`, `doctor`.
- Secrets: `secrets encrypt`, `decrypt`, `deploy`, `clean`, `check`.
- Env files: `env list`, `create`, `diff`, `materialize`, `audit`.
- Shell integration: `completions`.

For full command facts, read `references/commands.md`. For source hierarchy, runtime facts, and
known stale docs, read `references/truth-model.md`.
Loading