commitlydocs
← back to home

Install

The CLI is a single Node binary. From a clean shell to a paired device emitting signed attestations takes about thirty seconds.

## requirements

  • Node 20+ — the agent uses native fetch with AbortSignal, available since 18 but stable since 20.
  • git on $PATH — every project the agent touches must be a real git working tree.
  • OS keychain — Keychain Access (macOS), libsecret (Linux), or Credential Manager (Windows via WSL). Required for storing the GitHub token and Ed25519 key.
  • For the daemon: launchctl on macOS, or systemd --user on Linux. Both ship by default on supported systems.

## install

npm i -g commitly-agent
commitly-agent --help

If commitly-agent --help prints a list of commands, you're good. If it prints command not found, your npm global bin directory isn't on $PATH; add it and re-source your shell.

## first login

This pairs the machine. The browser handles OAuth; the CLI mints an Ed25519 keypair, stores the private half in your OS keychain, and registers the public half with the dashboard so future attestations from this machine are verifiable.

$ commitly-agent login
→ Open this URL in your browser to log in:
   https://commitly.dev/auth/cli?session=8f3a…

Waiting for authentication (times out in 5 minutes)...
✓ Authenticated. Credentials stored in OS keychain.
✓ Device paired. This machine can now emit signed timestamp attestations.

## verify

Run status against any git repo to confirm the agent can talk to the dashboard with the credentials it just stored.

$ commitly-agent status
  No daemon is currently running.

That's the expected output before you start a daemon. You're ready to pick a mode — read the command reference to see all eleven, or jump to Daemon mode for unattended operation.

## upgrade

npm i -g commitly-agent@latest
commitly-agent stop && commitly-agent start <projectPath>

Stop and restart the daemon after each upgrade so the new binary path is baked into the unit file.

## uninstall

commitly-agent stop
commitly-agent logout
npm uninstall -g commitly-agent
rm -rf ~/.commitly

That removes the daemon, the credentials, the binary, and the local spool. To delete the device record server-side as well, revoke it from the dashboard's Devices page.