Authentication

The CLI uses a secure device code OAuth flow for authentication. No API keys are needed — you authorize the CLI through your browser.

Logging in

hooklistener login

This starts the device code flow:

1. The CLI displays a user code (format: XXXX-XXXX)
2. Your browser opens to the authorization page
3. Enter the code and authorize the device
4. The CLI polls for authorization and stores the token

The token is valid for 60 days and is stored in your config file.

Force re-authentication

If you need to re-authenticate (e.g., switch accounts):

hooklistener login --force

Logging out

hooklistener logout

This clears the stored token from your config file. Your selected organization is preserved.

Token management

Tokens are stored in the CLI config file at:

~/.config/hooklistener/config.json

The CLI handles token management automatically. If a token expires, you'll be prompted to re-authenticate.

How the device flow works

The device code flow is designed for CLI applications:

1. CLI requests a device code from /api/v1/device
2. User visits https://app.hooklistener.com/device-codes and enters the code
3. CLI polls every 5 seconds for authorization
4. Once authorized, the CLI receives an access token
5. The code expires after 10 minutes if not used

This flow avoids exposing credentials in the terminal or storing API keys locally.

Troubleshooting

"Token expired" error — run hooklistener login to re-authenticate.

Browser didn't open — manually visit https://app.hooklistener.com/device-codes and enter the displayed code.

Authorization timeout — the code expires after 10 minutes. Run hooklistener login again to get a new code.