--- name: dckreg description: Install and use the dckreg CLI to create, inspect, import, rename, delete, restore and clean private Docker or OCI repositories; rotate registry credentials; configure Kamal; or diagnose dckreg operations safely. --- # dckreg agent instructions Use these instructions whenever a task involves private Docker/OCI repositories managed by dckreg. Read the complete document before running a mutating command. ## Install and verify Install only from the official HTTPS endpoint: ```sh curl -fsSL https://dckreg.d1cloud.io/install.sh | sh ``` The installer selects the current macOS/Linux and amd64/arm64 artifact, verifies its SHA-256 checksum, checks the embedded binary version, and atomically writes `~/.local/bin/dckreg`. It does not use `sudo`. Confirm that `~/.local/bin` is in `PATH`, then run: ```sh dckreg version dckreg --help ``` Do not reproduce or modify the installer. Do not bypass its checksum or version verification. ## Login and local state Run login in an interactive terminal: ```sh dckreg login https://dckreg.d1cloud.io ``` The human must enter the central management token directly at the hidden `Authentication token` prompt. Never ask the human to paste a token into chat. Never accept, print, log, summarize, or place a token in a command argument, environment transcript, URL, issue, or project file. The CLI verifies the token before saving it. Its settings and token live below the user's home directory: - `~/.dckreg/` — mode `0700` - `~/.dckreg/config.json` — server settings, mode `0600` - `~/.dckreg/credentials.json` — management token, mode `0600` - `~/.dckreg/update-check.json` — non-secret version-check state, mode `0600` Do not read, display, attach, copy, or edit credential files. `DCKREG_CONFIG_HOME` is only an explicit test/automation override. Before a protected operation, run: ```sh dckreg auth status ``` If login is missing or invalid, stop and ask the human to run the interactive login. Never invent a token or suggest `--token`; that flag intentionally does not exist. ## Updates dckreg periodically checks the authenticated server's public `/version` endpoint. If a newer version exists, it writes a notice to stderr without changing command JSON. Update with: ```sh dckreg update ``` The updater downloads the platform release over HTTPS, verifies the SHA-256 manifest and downloaded binary version, and atomically replaces the currently running executable. A failed update preserves the current executable. Do not replace this flow with an unverified download. ## Safe execution rules 1. Run `dckreg COMMAND --help` before a destructive or unclear action. 2. Use `--json` when output will be parsed. Update notices are emitted on stderr; parse stdout only. 3. Treat every returned repository password as a one-time secret. Store it immediately in the user's approved secret store without echoing it back. 4. Pass passwords only through hidden prompts or explicit `--password-stdin` / `--source-password-stdin` mechanisms. Never put passwords in arguments, URLs, YAML, logs, or chat. 5. Prefer inspect/status/dry-run before mutation. Preserve request IDs from errors, but redact headers, tokens, passwords, and credential files. 6. Stop on any validation, authentication, checksum, verification, or partial-operation error. Report what succeeded and what remains without exposing secrets. 7. Permanent purge is irreversible. Do not run it without an explicit user request naming the exact repository. ## Core repository workflow Create a private repository and request a password-free Kamal snippet: ```sh dckreg repo create checkout-api --show-kamal ``` Defaults are logical name/project `checkout-api`, repository path `app`, a derived dedicated username, and an auto-generated password. The returned password appears once. A custom repository path or username is optional: ```sh dckreg repo create checkout-api --repo-name checkout dckreg repo create checkout-api --username legacy-checkout dckreg repo create checkout-api --password ``` `--password` is a boolean switch that opens a double hidden prompt. For non-interactive trusted input use `--password-stdin`; never add a visible password value to the command. Inspect without exposing a password: ```sh dckreg repo list dckreg repo inspect checkout-api dckreg repo policy show checkout-api ``` Set quota and retention only when the requested values are known: ```sh dckreg repo policy set checkout-api --quota-gib 25 --retention-count 20 ``` ## Kamal The `--show-kamal` result has this shape and intentionally omits the password: ```yaml image: checkout-api/app registry: server: registry.d1cloud.io username: dckreg_checkout_api password: - KAMAL_REGISTRY_PASSWORD ``` Store the one-time password as `KAMAL_REGISTRY_PASSWORD`. Never write it into `deploy.yml` or return it in an agent message. ## Credential rotation Rotate a repository credential when requested or when compromise is suspected: ```sh dckreg repo credentials rotate checkout-api ``` The replacement password is shown once. Update all authorized consumers before discarding the old secret. Rotate the central dckreg management token only with explicit authorization: ```sh dckreg auth rotate --grace-period 30m ``` The CLI stores the newly returned management token under `~/.dckreg`. `dckreg logout` only removes local login state; it does not revoke the token globally. ## Rename Preview the current resource, then start a verified copy-and-switch rename: ```sh dckreg repo inspect checkout-api dckreg repo rename checkout-api checkout-service --keep-old-for 7d ``` Rename copies and verifies tags, indexes, and supported referrers before switching. Track asynchronous work with the job ID returned by the command: ```sh dckreg job inspect JOB_ID dckreg job watch JOB_ID ``` Do not assume completion until the job reaches a successful terminal state. ## Delete, restore, and purge Normal delete disables access and starts the configured restore window: ```sh dckreg repo inspect checkout-service dckreg repo delete checkout-service ``` Restore within that window: ```sh dckreg repo restore checkout-service ``` Permanent deletion is irreversible and requires exact name confirmation: ```sh dckreg repo delete checkout-service --purge --confirm checkout-service ``` Run purge only when the user explicitly requested permanent deletion of that exact repository and the preceding inspect output proves the target. ## Docker Hub import Public import never modifies the source: ```sh dckreg repo import docker.io/example/app --name app --all-tags ``` For a private source, provide the source username and enter the password through the hidden prompt: ```sh dckreg repo import docker.io/example/app --name app --all-tags --source-username USER --source-password ``` Source credentials remain in memory only. Public work resumes after a server restart. Private work waits for credentials; retry only failed or missing items: ```sh dckreg job list dckreg job inspect JOB_ID dckreg job retry JOB_ID --source-password dckreg job watch JOB_ID ``` ## Cleanup and storage Inspect first, then use dry-run before cleanup mutation: ```sh dckreg cleanup status dckreg cleanup run --dry-run dckreg cleanup run dckreg storage status ``` Do not equate Harbor accounting with physical object-storage bytes; shared layers can make them differ. ## Diagnostics and API Use these non-secret diagnostics: ```sh dckreg doctor dckreg version dckreg auth status ``` Public service references: - Human documentation: `https://dckreg.d1cloud.io/docs` - Agent instructions: `https://dckreg.d1cloud.io/skill.md` - OpenAPI contract: `https://dckreg.d1cloud.io/openapi.json` - Health: `https://dckreg.d1cloud.io/healthz` - Readiness: `https://dckreg.d1cloud.io/readyz` Server errors include a request ID. Report that ID, command name, exit code, and redacted error message. Never attach `~/.dckreg`, Authorization headers, `.env` files, Docker credential configuration, raw Harbor errors, or any one-time credential.