Skip to main content

CLI reference

The agent binary is both a control CLI and a background worker. When you pass --worker (normally only the agent does this to itself), it runs the tracking loop. All other invocations are user-facing commands.

Synopsis​

Analog-WakaTime-Agent                 # same as start
Analog-WakaTime-Agent start
Analog-WakaTime-Agent stop
Analog-WakaTime-Agent login
Analog-WakaTime-Agent status
Analog-WakaTime-Agent logout
Analog-WakaTime-Agent help

On Windows use Analog-WakaTime-Agent.exe with the same subcommands.

Aliases for stop: quit, shutdown.
Help aliases: -h, --help.

start (default)​

Purpose: enable tracking and make sure the background worker is running. If you are not logged in, enter the login flow.

What it does:

  1. Ensures data/ and logs/ exist
  2. Removes data/agent.disabled if present
  3. Spawns the detached worker when needed
  4. Opens the DB and checks for a stored auth session
  5. If unauthenticated → runs login until success

Example:

./Analog-WakaTime-Agent start

stop​

Purpose: disable tracking and shut down the worker.

What it does:

  1. Creates data/agent.disabled
  2. Signals / terminates the worker process
  3. Removes the PID file when the process is gone

Example:

./Analog-WakaTime-Agent stop

Output:

Agent stopped.
note

logout does not stop tracking. It only clears the auth session. Use stop when you want the worker off.

login​

Purpose: authenticate (or re-authenticate) against the gateway. Loops until login succeeds or you interrupt the process.

You can choose:

  1. Browser verification code (OAuth Device Flow) — default
    • Agent prints a URL and a short user code
    • You confirm in the browser
    • Agent polls until the device is authorized
  2. Email + password — classical form login over HTTPS

After success, the session is stored in data/agent.db.

Example:

./Analog-WakaTime-Agent login

start already calls this path when needed, so a separate login is mainly for fixing auth without restarting your mental model of “is tracking on?”.

status​

Purpose: print a short health summary. If tracking is not disabled, it also tries to ensure the background worker is up.

Typical fields:

Agent: running (pid 4242)
Account: authenticated
Logs: logs/agent.log
Offline sync queue: 12

Possible agent lines:

LineMeaning
Agent: running (pid …)Worker process is alive
Agent: starting...Enabled, but PID not healthy yet
Agent: stopped (tracking disabled)data/agent.disabled is present

Account lines: authenticated or waiting for login.

Platform hints (Linux only):

  • GNOME helper missing → restart agent after extension install
  • KDE helper missing → restart agent, then focus any window once

logout​

Purpose: clear the local auth session.

Tracking continues if the worker is still running, but sync will pause until you log in again (pending rows stay queued offline).

./Analog-WakaTime-Agent logout

help​

Prints usage text for the commands above.

Background worker behavior​

  • Spawned by start / status (when enabled) as Analog-WakaTime-Agent --worker
  • Redirects stdin/stdout/stderr to the null device
  • On Unix, starts in a new session (Setsid)
  • On Windows, starts in a new process group with a hidden window
  • Writes its PID to data/agent.pid
  • Restarts its inner loop after crashes with a short delay, unless disabled
  • Honors SIGTERM / SIGINT on Unix for graceful shutdown

You normally never invoke --worker yourself.