CLI Reference — escribano-query

Agent-native work memory interface. JSON to stdout, logs to stderr, exit 0 on success.

Quickstart

escribano-query                           # today's activity
escribano-query recent --since 2h         # last 2 hours
escribano-query search "swift actor"      # full-text search
escribano-query entities --since 24h      # tools, languages, apps
escribano-query status                    # health + license info

Command index

Command	What it does
`today`	Activity from today (default)
`yesterday`	Activity from yesterday
`this-week`	Activity from this week
`last-active-day`	Most recent day with activity
`recent`	Activity in a rolling window (`--since 2h`)
`range`	Activity between two dates
`search`	Full-text search across observations
`entities`	Aggregated tools, languages, apps, etc.
`support-context`	Structured summary for support drafts
`status`	Health check, DB stats, license info
`activate`	Activate a license key
`deactivate`	Remove license, revert to free tier

Time-based queries

Four shortcuts that return a moment timeline for a fixed window:

escribano-query today
escribano-query yesterday --json
escribano-query this-week --compact
escribano-query last-active-day        # falls back to today if empty

Command	Window
`today`	Today (default if no command given)
`yesterday`	Yesterday
`this-week`	Current ISO week
`last-active-day`	Most recent day with observations

Shared flags: --json, --compact, --full, --limit N

`recent` — moment timeline by duration

escribano-query recent --since 2h
escribano-query recent --since 30m --images
escribano-query recent --since 1d --compact --json

Flag	Required	Description
`--since <duration>`	✓	`30m`, `2h`, `1d`, `1w`
`--images`		Include `image_path` (explicit escalation)
`--compact` / `--full`		Toggle `vlm_description`
`--limit N`		Cap results
`--json`		Force JSON output

Returns observations bucketed by the given window with entity summaries.

`range` — custom time range

escribano-query range --from 2026-04-01 --to 2026-04-07
escribano-query range --from 2026-04-20T10:00:00Z --to 2026-04-20T18:00:00Z --json

Flag	Required	Description
`--from <iso>`	✓	Start date — `yyyy-MM-dd` or ISO 8601
`--to <iso>`	✓	End date — `yyyy-MM-dd` or ISO 8601
`--compact` / `--full`		Toggle `vlm_description`
`--limit N`		Cap results
`--json`		Force JSON output

`search` — full-text (FTS5, BM25 ranked)

escribano-query search "debugging" --since 4h
escribano-query search "swift actor" --collapse
escribano-query search "coolify" --limit 10

Required: keyword string

Flag	Description
`--since <duration>`	Time window
`--from <date>` / `--to <date>`	Explicit date range
`--latest`	Return only the most recent match
`--collapse`	Deduplicate by description
`--compact`	Omit `vlm_description`
`--images`	Include `image_path`
`--limit N`	Cap results — default `50`, max `200`

Search syntax
swift actor → OR — matches swift or actor
"swift actor" → exact phrase
swift AND actor → both terms required

`entities` — aggregated data

escribano-query entities --since 24h
escribano-query entities --since 2h --kind programming_language

Flag	Description
`--since <duration>`	Time window — default `24h`
`--kind <entity_kind>`	Filter by kind
`--limit N`	Cap results — default `100`

Entity kinds: software_tool · programming_language · framework · file_path · url · git_branch · error_message · app · company · website · person · location · event

No license check — works on any tier.

`support-context` — support summary

escribano-query support-context --json

Structured context summary for support drafts and agent handoffs. Aggregated signals only — no raw observations.

`status` — health and license

escribano-query status --json

Returns DB stats, operational health, and license info. No license check.

`activate` / `deactivate` — license

escribano-query activate ESC-BETA-XXXX
escribano-query activate ESC-PRO-XXXX
escribano-query deactivate

activate requires internet. deactivate reverts to the free tier (7-day history limit).

Global flags

Flag	Applies to	Description
`--since <duration>`	`recent`, `search`, `entities`	Time window — `30m`, `2h`, `1d`, `1w`
`--from` / `--to`	`range`, `search`	Explicit date range
`--compact`	most	Omit `description` and `topics`
`--full`	most	Include `description` and `topics` (default)
`--collapse`	`search`	Deduplicate results by description
`--images`	`recent`, `search`	Include `image_path` (explicit escalation)
`--kind <entity_kind>`	`entities`	Filter by entity kind
`--limit N`	most	Cap result count
`--json`	all	Force JSON output (default when piped)
`--help, -h`	all	Show help
`--version, -v`	all	Show version

Output schema

Every JSON response uses this envelope:

{
  "ok": true,
  "api_version": 2,
  "data": { ... },
  "meta": {
    "current_date": "2026-04-20",
    "current_datetime": "2026-04-20T11:00:00+02:00",
    "timezone": "Europe/Berlin"
  }
}

Anchor "today" to meta.current_date — don't rely on the agent's system clock.

Errors use the same envelope with ok: false:

{
  "ok": false,
  "error": {
    "code": "LICENSE_ERROR",
    "message": "Search requires a Pro license for history older than 7 days."
  }
}

Code	Meaning
`DB_NOT_FOUND`	Database file missing
`DB_LOCKED`	Database busy (WAL contention)
`SCHEMA_MISMATCH`	Schema version mismatch
`INVALID_TIME_RANGE`	Bad date format or inverted range
`LICENSE_ERROR`	License invalid, expired, or network failure
`UNKNOWN_ERROR`	Catch-all

License tiers

Capability	Free	Pro
History window	7 days	Unlimited
`search` with `--since >7d` or `--from >7d ago`	✗	✓
`entities`, `recent`, `status`, `support-context`	✓	✓
Activation	—	`escribano-query activate ESC-PRO-XXXX`

State transitions:

stateDiagram-v2
    [*] --> Free
    Free --> Pro: activate ESC-PRO-XXXX
    Free --> Beta: activate ESC-BETA-XXXX
    Pro --> Free: deactivate
    Beta --> Free: deactivate

Run escribano-query status at any time to check your current tier.

CLI Reference — escribano-query

Command index

Time-based queries

recent — moment timeline by duration

range — custom time range

search — full-text (FTS5, BM25 ranked)

entities — aggregated data

support-context — support summary

status — health and license

activate / deactivate — license