Skip to main content

Documentation Index

Fetch the complete documentation index at: https://authsome.agentr.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

Authsome writes an append-only event log to ~/.authsome/audit.log. Every line is a single JSON object. The format is intentionally readable and meant to be tailed, grepped, or forwarded to your existing log pipeline.

​
File location

~/.authsome/audit.log
Override via AUTHSOME_HOME if you keep state elsewhere. See Filesystem layout. The file is not encrypted. It contains no secret values; just event metadata. Treat it like any operational log.

​
Wire format

One JSON object per line, UTF-8, terminated with \n. No trailing comma, no top-level array. 
{"timestamp": "2026-05-11T14:32:01.482910+00:00", "event": "login", "provider": "github", "connection": "default"}
{"timestamp": "2026-05-11T14:32:05.913220+00:00", "event": "get", "provider": "github", "connection": "default", "field": "access_token"}
{"timestamp": "2026-05-11T14:33:18.001456+00:00", "event": "export", "provider": "openai", "connection": "default", "format": "env"}
Every entry has:
FieldTypeDescription
timestampstring (ISO-8601, UTC)When the event was written. Includes +00:00 suffix.
eventstringOne of the event types below.
Each event type may add typed fields. None values are stripped before write, so absent fields mean “not applicable”.

​
Event types

EventWritten fromCommon fieldsNotes
loginCLIprovider, connection, profile, identity. On failure also status: "failure".Successful logins have no status field.
logoutCLIprovider, connectionLogical removal of a connection record from the local store. The provider is not contacted.
revokeCLIprovider, connection: "all"The provider’s revocation endpoint was called (where supported). All connections + client credentials for the provider are cleared.
removeCLIprovider, connection: "all"Provider definition is uninstalled (custom) or reset (bundled). All local state for the provider is cleared.
getCLIprovider, connection, fieldfield is the specific field requested, or "all" if the user dumped the whole record. The value itself is never logged.
exportCLIprovider, connection, format (env or json)Logged whenever a secret leaves the vault for use. Secret values are never logged.
registerCLIprovider, endpointsA custom provider was registered. endpoints is a summary of the URLs declared in the JSON.
scanCLIprovider, connection, source, env_varOne entry per credential imported via authsome scan --import. source is env or a .env file path.
refresh_failedAuthServiceprovider, connection, profile, error, fallback_availableEmitted when token refresh fails. Successful refresh is silent. fallback_available: true means the still-unexpired cached token was returned.
The set of events grows over time. Parse defensively: treat unknown event values as opaque and skip them rather than failing.

​
Read the log

uvx authsome log              # last 50 entries, pretty-printed
uvx authsome log -n 200       # last 200
uvx authsome log --json       # one JSON object per line, unmodified
For programmatic consumption, prefer --json. The default output is pretty-printed for terminals and not stable across versions.

​
Tail in real time

tail -f ~/.authsome/audit.log
Every CLI invocation that mutates state appends. Refresh events from the auth service append too.

​
Forwarding

The log file is plain JSON Lines, so any log shipper that handles JSONL works. Vector, Fluent Bit, Promtail, Filebeat, and journald can all tail this file directly. 
# Vector example
sources:
  authsome:
    type: file
    include: ["/home/*/.authsome/audit.log"]
    encoding:
      codec: json

​
What the log does and doesn’t contain

Contains:
  • Timestamps for every significant action.
  • Provider and connection names.
  • Event types for login, logout, revoke, remove, get, export, register, and refresh.
  • Outcome metadata (status: "failure" on failed logins, refresh outcome strings).
Does not contain:
  • Access tokens, refresh tokens, API keys, client_secrets, or any other secret value.
  • Decrypted credential records.
  • Browser-bridge form submissions.
  • Network request bodies passed through the proxy.
If you find a secret in the audit log, that’s a bug. Report it through Responsible disclosure.

​
Retention

Authsome does not rotate the audit log itself. Use logrotate, journalctl, or your log shipper’s retention policy. Typical entries are 200-400 bytes, so growth is slow but unbounded.

​
What’s next

CLI reference

The log command and every other CLI surface.

Filesystem layout

Where the audit log sits and what’s around it.

Threat model

How the audit log fits into authsome’s overall security posture.

HTTP daemon API

The daemon routes that emit audit events.