Advanced Feature

CLI

Query your local time.md database from Terminal, scripts, and coding agents.

Local read access

The CLI reads local SQLite databases on demand. It does not upload your activity data to time.md.

Review boundaries

Install the CLI

Open Settings → CLI Access and choose install. time.md creates a symlink in your user-writable bin directory:

~/.local/bin/timemd

If ~/.local/bin is not on your shell PATH, add it with the snippet shown by the app:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Commands

The CLI prints JSON to stdout. Command aliases omit the get_ prefix, so top-apps resolves to get_top_apps.

timemd help

timemd list-commands

timemd today --limit 5

timemd top-apps --since 7d --limit 20

timemd sessions --since today --app-name Slack --limit 50

timemd call get_heatmap --since 30d --stream-type app_usage

Arguments can be passed as flags or as a JSON object:

timemd top-apps --stream-type app_usage --limit=20

timemd top-apps --json '{"since":"30d","limit":10}'

Read-only SQL

timemd sql accepts one read-only SELECT, WITH, or EXPLAIN statement.

timemd schema

timemd sql '
  SELECT app_name, SUM(duration_seconds) AS seconds
  FROM usage
  GROUP BY app_name
  ORDER BY seconds DESC
  LIMIT 10
'

The category database is attached as cat. Input-tracking tables are attached as inp when present.

Coding-agent usage

Ask an agent to run the CLI directly. Recommended pattern:

  1. Run timemd schema or timemd list-commands first.
  2. Prefer built-in commands like today, top-apps, and sessions.
  3. Use timemd sql only for questions not covered by a built-in command.
  4. Treat returned JSON as local/private user data.
Run `timemd schema`, then use `timemd sql` to find my top apps this week. Return a short summary and include the exact SQL you used.

Agent skills

time.md bundles agent-agnostic SKILL.md guides with the app. In Settings → CLI Access → Agent Skills, copy the bundled skills path, reveal the folder in Finder, or copy a ready-to-paste prompt that asks your agent to install the skills into its own skills/custom-instructions location.

time.md.app/Contents/Resources/skills/timemd-cli/SKILL.md
time.md.app/Contents/Resources/skills/timemd-cli-sql/SKILL.md
time.md.app/Contents/Resources/skills/timemd-cli-reports/SKILL.md
time.md.app/Contents/Resources/skills/timemd-cli-input/SKILL.md
time.md.app/Contents/Resources/skills/timemd-cli-troubleshooting/SKILL.md

Copy these files into any agent that supports skills or custom instructions. time.md does not auto-register agents.

Data paths

By default, timemd reads databases in ~/Library/Application Support/time.md.

TIMEMD_DATA_DIR=/path/to/time-md-data timemd today
SCREENTIME_DB_PATH=/path/to/screentime.db timemd schema

Privacy boundaries

  • The CLI reads local SQLite files and prints local JSON output.
  • time.md does not receive CLI query results.
  • Any terminal, script, or agent that runs timemd can see the rows returned by that command.
  • Input-tracking commands return empty results unless you enabled the underlying input-tracking feature.