# 🔎 CLI Reference — escribano-query

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

> **Quickstart**
>
> ```bash
> 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`](#time-based-queries) | Activity from today *(default)* |
| [`yesterday`](#time-based-queries) | Activity from yesterday |
| [`this-week`](#time-based-queries) | Activity from this week |
| [`last-active-day`](#time-based-queries) | Most recent day with activity |
| [`recent`](#recent-moment-timeline) | Activity in a rolling window (`--since 2h`) |
| [`range`](#range-custom-time-range) | Activity between two dates |
| [`search`](#search-full-text-fts5-bm25-ranked) | Full-text search across observations |
| [`entities`](#entities-aggregated-data) | Aggregated tools, languages, apps, etc. |
| [`support-context`](#support-context-support-summary) | Structured summary for support drafts |
| [`status`](#status-health-and-license) | Health check, DB stats, license info |
| [`activate`](#activate--deactivate-license) | Activate a license key |
| [`deactivate`](#activate--deactivate-license) | Remove license, revert to free tier |


---

## Time-based queries

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

```bash
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

```bash
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

```bash
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)

```bash
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

```bash
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

```bash
escribano-query support-context --json
```

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


---

## `status` — health and license

```bash
escribano-query status --json
```

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


---

## `activate` / `deactivate` — license

```bash
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:

```json
{
  "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`:

```json
{
  "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:

```mermaid
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.