98b9bc3c93
Agents had no guidance on which Woodpecker instance serves which repos, leading to repeated 401 failures and workaround attempts. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
163 lines
5.1 KiB
Markdown
163 lines
5.1 KiB
Markdown
# Machine-Level Tool Reference
|
|
|
|
Centralized reference for tools, credentials, and CLI patterns available across all projects.
|
|
Project-specific tooling belongs in the project's `AGENTS.md`, not here.
|
|
|
|
All tool suites are located at `~/.config/mosaic/tools/`.
|
|
|
|
## Tool Suites
|
|
|
|
### Git Wrappers (Use First)
|
|
|
|
Mosaic wrappers at `~/.config/mosaic/tools/git/*.sh` handle platform detection and edge cases. Always use these before raw CLI commands.
|
|
|
|
```bash
|
|
# Issues
|
|
~/.config/mosaic/tools/git/issue-create.sh
|
|
~/.config/mosaic/tools/git/issue-close.sh
|
|
|
|
# PRs
|
|
~/.config/mosaic/tools/git/pr-create.sh
|
|
~/.config/mosaic/tools/git/pr-merge.sh
|
|
|
|
# Milestones
|
|
~/.config/mosaic/tools/git/milestone-create.sh
|
|
|
|
# CI queue guard (required before push/merge)
|
|
~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge
|
|
```
|
|
|
|
### Code Review (Codex)
|
|
|
|
```bash
|
|
~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted
|
|
~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted
|
|
```
|
|
|
|
### Infrastructure — Portainer
|
|
|
|
```bash
|
|
~/.config/mosaic/tools/portainer/stack-status.sh -n <stack-name>
|
|
~/.config/mosaic/tools/portainer/stack-redeploy.sh -n <stack-name>
|
|
~/.config/mosaic/tools/portainer/stack-list.sh
|
|
~/.config/mosaic/tools/portainer/endpoint-list.sh
|
|
```
|
|
|
|
### Infrastructure — Coolify
|
|
|
|
```bash
|
|
~/.config/mosaic/tools/coolify/project-list.sh
|
|
~/.config/mosaic/tools/coolify/service-list.sh
|
|
~/.config/mosaic/tools/coolify/service-status.sh -u <uuid>
|
|
~/.config/mosaic/tools/coolify/deploy.sh -u <uuid>
|
|
~/.config/mosaic/tools/coolify/env-set.sh -u <uuid> -k KEY -v VALUE
|
|
```
|
|
|
|
### Identity — Authentik
|
|
|
|
```bash
|
|
~/.config/mosaic/tools/authentik/user-list.sh
|
|
~/.config/mosaic/tools/authentik/user-create.sh -u <username> -n <name> -e <email>
|
|
~/.config/mosaic/tools/authentik/group-list.sh
|
|
~/.config/mosaic/tools/authentik/app-list.sh
|
|
~/.config/mosaic/tools/authentik/flow-list.sh
|
|
~/.config/mosaic/tools/authentik/admin-status.sh
|
|
```
|
|
|
|
### CI/CD — Woodpecker
|
|
|
|
Multi-instance support: `-a <instance>` selects a named instance. Omit `-a` to use the default from `woodpecker.default` in credentials.json.
|
|
|
|
| Instance | URL | Serves |
|
|
|----------|-----|--------|
|
|
| `mosaic` (default) | ci.mosaicstack.dev | Mosaic repos (git.mosaicstack.dev) |
|
|
| `usc` | ci.uscllc.com | USC repos (git.uscllc.com) |
|
|
|
|
```bash
|
|
# List recent pipelines
|
|
~/.config/mosaic/tools/woodpecker/pipeline-list.sh [-r owner/repo] [-a instance]
|
|
|
|
# Check latest or specific pipeline status
|
|
~/.config/mosaic/tools/woodpecker/pipeline-status.sh [-r owner/repo] [-n number] [-a instance]
|
|
|
|
# Trigger a build
|
|
~/.config/mosaic/tools/woodpecker/pipeline-trigger.sh [-r owner/repo] [-b branch] [-a instance]
|
|
```
|
|
|
|
Instance selection rule: match `-a` to the git remote host of the target repo. If the repo is on `git.uscllc.com`, use `-a usc`. If on `git.mosaicstack.dev`, use `-a mosaic` (or omit, since it's the default).
|
|
|
|
### DNS — Cloudflare
|
|
|
|
Multi-instance support: `-a <instance>` selects a named instance (e.g. `personal`, `work`). Omit `-a` to use the default from `cloudflare.default` in credentials.json.
|
|
|
|
```bash
|
|
# List zones (domains)
|
|
~/.config/mosaic/tools/cloudflare/zone-list.sh [-a instance]
|
|
|
|
# List DNS records (zone by name or ID)
|
|
~/.config/mosaic/tools/cloudflare/record-list.sh -z <zone> [-a instance] [-t type] [-n name]
|
|
|
|
# Create DNS record
|
|
~/.config/mosaic/tools/cloudflare/record-create.sh -z <zone> -t <type> -n <name> -c <content> [-a instance] [-p] [-l ttl] [-P priority]
|
|
|
|
# Update DNS record
|
|
~/.config/mosaic/tools/cloudflare/record-update.sh -z <zone> -r <record-id> -t <type> -n <name> -c <content> [-a instance] [-p] [-l ttl]
|
|
|
|
# Delete DNS record
|
|
~/.config/mosaic/tools/cloudflare/record-delete.sh -z <zone> -r <record-id> [-a instance]
|
|
```
|
|
|
|
### IT Service — GLPI
|
|
|
|
```bash
|
|
~/.config/mosaic/tools/glpi/ticket-list.sh
|
|
~/.config/mosaic/tools/glpi/ticket-create.sh -t <title> -c <content>
|
|
~/.config/mosaic/tools/glpi/computer-list.sh
|
|
~/.config/mosaic/tools/glpi/user-list.sh
|
|
```
|
|
|
|
### Health Check
|
|
|
|
```bash
|
|
# Check all configured services
|
|
~/.config/mosaic/tools/health/stack-health.sh
|
|
|
|
# Check a specific service
|
|
~/.config/mosaic/tools/health/stack-health.sh -s portainer
|
|
|
|
# JSON output for automation
|
|
~/.config/mosaic/tools/health/stack-health.sh -f json
|
|
```
|
|
|
|
### Shared Credential Loader
|
|
|
|
```bash
|
|
# Source in any script to load service credentials
|
|
source ~/.config/mosaic/tools/_lib/credentials.sh
|
|
load_credentials <service-name>
|
|
# Supported: portainer, coolify, authentik, glpi, github, gitea-mosaicstack, gitea-usc, woodpecker, cloudflare
|
|
```
|
|
|
|
## Git Providers
|
|
|
|
| Instance | URL | CLI | Purpose |
|
|
|----------|-----|-----|---------|
|
|
| (add your git providers here) | | | |
|
|
|
|
## Credentials
|
|
|
|
**Location:** (configure your credential file path)
|
|
**Loader:** `source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials <service>`
|
|
|
|
**Never expose actual values. Never commit credential files.**
|
|
|
|
## CLI Gotchas
|
|
|
|
(Add platform-specific CLI gotchas as you discover them.)
|
|
|
|
## Safety Defaults
|
|
|
|
- Prefer `trash` over `rm` when available — recoverable beats gone forever
|
|
- Never run destructive commands without explicit instruction
|
|
- Write it down — "mental notes" don't survive session restarts; files do
|