# AGENTS.md — DNS CLI tooling

This directory holds the `dns-cli` Docker container — a bash CLI over the
Technitium DNS Server REST API. Every Crush session that works on or with
this tool should read this file first.

## Connection & invocation

Invoke the real container with `docker run`. Credentials come from the
centralized credential store (see `tooling-cli/KNELCredsManager`):

```bash
docker run --rm --env-file ~/.creds/technitium.env \
    git.knownelement.com/reachableceo/dns-cli:latest <command>
```

There is intentionally **no `bin/` wrapper** — invoke the real container, as
the project-wide rules require. For readability in an interactive session you
may define a throwaway shell alias (do not commit one):

```bash
alias dns='docker run --rm --env-file ~/.creds/technitium.env \
    git.knownelement.com/reachableceo/dns-cli:latest'
```

The examples below write `dns <cmd>` for brevity; expand it to the full
`docker run` line (or set the alias) before running.

| Item | Value |
|------|-------|
| Instance | `http://pfv-netinfra-01.knel.net:5380` |
| Default zone | `knel.net` |
| Credentials | `~/.creds/technitium.env` (`TECHNITIUM_URL`, `TECHNITIUM_DNS_TOKEN`, `TECHNITIUM_DNS_ZONE`) |
| CLI image | `git.knownelement.com/reachableceo/dns-cli:latest` |
| Source | `src/dns_cli.sh` in this directory |

## Quick start

```bash
# List all zones:
dns zones

# List records in the default zone:
dns list

# Search for a record:
dns search ns1

# Resolve a name:
dns get pfv-netinfra-01
```

## Command reference

| Command | Description |
|---------|-------------|
| `zones` | List all zones. |
| `list [zone]` | List records in a zone (default: `TECHNITIUM_DNS_ZONE`). |
| `get <name>` | Resolve a record via `dig` (A/AAAA). |
| `add <name> <ip> [ttl]` | Add an A record with auto-PTR (default TTL 3600). |
| `delete <name> <ip>` | Delete an A record. |
| `flush` | Flush the DNS cache. |
| `search <pattern>` | Search records by name pattern (case-insensitive). |

## Patterns

### Pattern: add a new DNS record
1. `dns search <hostname>` — check if the name already exists.
2. `dns add <hostname> <ip>` — creates the A record with auto-PTR.
3. `dns get <hostname>` — verify resolution.
4. `dns flush` — flush cache so the new record is immediately resolvable.

### Pattern: before you act
- Always `dns search <pattern>` or `dns list` before adding/deleting —
  confirm current state so you don't create duplicates or delete the wrong
  record.
- **Never delete a record** unless the user explicitly asks.
- PTR records are auto-created on `add` and auto-deleted on `delete`.

## Git workflow

### Atomic commits
Each commit is **one logical change**. Stage precisely (`git add <file>`,
not `git add -A`).

### Conventional commit messages
```
<type>(<optional scope>): <imperative subject>

<optional body — why, not what>
```

Types: `feat`, `fix`, `docs`, `refactor`, `chore`, `style`.

- Subject line under 72 chars, lowercase, imperative mood.
- No period at end of subject.
- Body wrapped at 72 chars, explains **why** the change exists.