Registry Credentials

Registry credentials let MacTain authenticate to private registries for image pull and push workflows. Credentials are stored by registry host and are Keychain-backed.

Command Reference

Command	Description	Typical use
`mactain registry credentials set --host <host> --username <username> --secret-stdin`	Creates or updates credentials for a registry host.	Store credentials without putting the secret on the command line.
`mactain registry credentials list`	Lists configured credential entries without secret values.	Confirm which hosts have credentials.
`mactain registry credentials test --host <host>`	Tests authentication using stored credentials.	Verify credentials before pull or push.
`mactain registry credentials remove --host <host>`	Removes credentials for a host.	Delete credentials that are no longer needed.
`mactain registry credentials delete --host <host>`	Alias for remove.	Compatibility with delete wording.

Defaults And Behavior

Credential entries are keyed by registry host, such as ghcr.io, registry-1.docker.io, or localhost:5000.
set reads the credential secret from stdin with --secret-stdin.
list returns non-secret metadata only.
test uses stored credentials; it does not take the secret value directly.
remove and delete remove the credential entry for one host.
Use JSON output when automating credential checks, but do not log secret values before piping them into MacTain.

Practical Use Cases

Use case: store credentials for a private registry

Use this when pulls or pushes to a registry host require authentication.

printf '%s' "$GHCR_TOKEN" | \
  mactain registry credentials set \
    --host ghcr.io \
    --username "$GHCR_USER" \
    --secret-stdin
mactain registry credentials test --host ghcr.io

Do not paste tokens into shell history. Prefer environment variables, a password manager handoff, or another secure stdin source.

Use case: see which registries are configured

Use this before troubleshooting a private image pull.

mactain registry credentials list
mactain registry credentials list --json

The list output is metadata-only and should not contain credential secrets.

Use case: remove stale credentials

Use this when a token is revoked, rotated, or no longer needed.

mactain registry credentials remove --host ghcr.io
mactain registry credentials list

After removal, private image pull and push workflows for that host may fail until credentials are set again.

Troubleshooting Entry Points

Pull fails for a private image: run mactain registry credentials test --host <host>.
Docker Hub auth fails: confirm whether the host should be registry-1.docker.io.
Push fails after a token rotation: update the credential with set and test again.

Next Steps

Continue to Images for pull, push, tag, import, export, and monitor commands. Continue to Build images before pushing a newly built image.