credctl daemon

Synopsis

credctl daemon start [flags]
credctl daemon stop
credctl daemon status

Description

The credential daemon caches cloud credentials in memory after the first Touch ID authentication. Subsequent credctl auth calls return cached credentials instantly without re-triggering Touch ID or making cloud API calls.

How it works: The daemon listens on a Unix socket at ~/.credctl/daemon.sock. When credctl auth runs, it checks for the socket first — if the daemon is running, credentials are served from the in-memory cache. If not, credctl auth falls back to the normal direct path. No configuration changes are needed.

What’s cached: AWS STS credentials and GCP access tokens, keyed by provider and format. Credentials are held in process memory only — never written to disk. Restarting the daemon clears the cache.

When credentials refresh: The daemon does not proactively refresh credentials (that would require unsolicited Touch ID prompts). Instead, requests arriving within 5 minutes of credential expiry trigger a re-fetch. All other requests return cached credentials instantly.

Current limitations

Foreground only. credctl daemon start runs in the current terminal session. Closing the terminal stops the daemon. You can use nohup credctl daemon start & as a workaround.
No auto-start. The daemon does not start automatically on login. You must start it manually each session.
No launchd integration yet. credctl daemon install / credctl daemon uninstall for macOS LaunchAgent support is planned.

Commands

`credctl daemon start`

Starts the daemon, listening on ~/.credctl/daemon.sock.

Flag	Type	Default	Description
`--idle-timeout`	duration	`30m`	Shut down automatically after this duration of inactivity. Set to `0` to disable.
`--foreground`	boolean	`true`	Run in foreground. Currently the only supported mode.

The daemon shuts down automatically after the idle timeout (reset on each request). It also shuts down cleanly on SIGTERM or SIGINT (Ctrl+C).

`credctl daemon stop`

Stops a running daemon by sending SIGTERM to the process in the PID file (~/.credctl/daemon.pid).

`credctl daemon status`

Queries the running daemon and displays uptime and cache state.

Example output:

Daemon running (PID 12345)
  Uptime:  42m15s
  Started: 2026-03-16T10:00:00Z
  Cache:
    aws:credential_process: valid (expires 2026-03-16T11:00:00Z)
    gcp:executable: needs refresh (expires 2026-03-16T10:43:00Z)

If the daemon is not running:

Daemon is not running

Example workflow

# Start the daemon (in a dedicated terminal, or backgrounded)
credctl daemon start

# First auth — Touch ID prompt, STS call, credentials cached
credctl auth

# Second auth — instant, no Touch ID
credctl auth

# Check cache state
credctl daemon status

# Stop when done
credctl daemon stop

Security

The Unix socket is created with 0600 permissions inside ~/.credctl/ (which is 0700). Only the owning user can connect.
Credentials exist in process memory only — never serialised to disk.
The PID file uses an exclusive file lock (flock) to prevent duplicate daemon instances.
Touch ID is still required for every credential fetch — the daemon reduces frequency (once per credential lifetime instead of once per tool invocation), not eliminates it.
Error responses to clients use generic messages; detailed errors are logged to stderr only.