Metadata-Version: 2.5
Name: the-almanac
Version: 2.0.4
Summary: The CLI for hosted Almanac.
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: keyring<26,>=25
Requires-Dist: pydantic<3,>=2.12
Requires-Dist: pyjwt<3,>=2.10
Description-Content-Type: text/markdown

# Almanac CLI

A thin client for hosted Almanac. Each command is one `POST /v2/cli` carrying the
words, stdin and the bytes of any local files the words name (`@FILE`, `--patch
FILE`, `--cursor @FILE`, `--from FILE`, `--file FILE`, `wiki add PATH`). The API
parses the same grammar from `shared/commands` and owns data and write outcomes;
the CLI only reads those files, signs in, and saves results and downloads.

```sh
almanac login
almanac search "pricing" --from alex@example.com
almanac list --kind task --state open
almanac read people/alex-kim
almanac history --since chg_48211
almanac email reply REF --body @reply.md --draft
almanac messages send --in '#general' --body 'Hello'
almanac calendar respond REF accept
almanac files share REF --add-with alex@example.com
almanac accounts
almanac help "forward email"
```

Data commands print the API's JSON document. Help prints plain text. Read results
contain `items`, write results `item`; a failure is `{"ok": false, "error":
PROBLEM}` with the API's RFC 9457 Problem. Save a full document with `--output FILE`; stdout then omits `items`
and includes the file path and count. `--cursor @FILE` continues from the `next`
saved in that file. Downloads use `--output-dir DIR` and never replace an
existing file.

Read before editing; pass the returned revision as `--expect`. Intents such as
archive, react and restore need no revision. Every write receives a request key;
repeat it only with identical input. Unknown write outcomes are never retried
blindly.

One credential is chosen, never falling through: `--user` (stored sign-in),
`--token`, `ALMANAC_TOKEN_FILE` (a sandbox run's token, re-minted into the file),
`ALMANAC_TOKEN`, then the stored sign-in from `almanac login`. `ALMANAC_API_URL`
selects the server.

`almanac batch` reads up to 20 JSON argv arrays from stdin and sends them as one
request. Every write line needs its own explicit `--request-key`. The whole batch
is validated before it starts, then runs in order and reports each result.

Use `--draft` on `email send`, `email reply`, or `email forward` to hold an
Almanac draft (`dft_…`); use `drafts edit|send|archive|restore` to manage it.
Find held drafts with `almanac list --kind draft`, then inspect a returned ref
with `almanac read DRAFT_REF` before editing or sending it.

Public research uses `apps web sources` and `apps web describe OPERATION` for
available sources and native filters. `apps web search QUERY --source SOURCE
--parameters @filters.json --output result.json` preserves the original data,
resources, assets and continuation. Read a returned resource with `read RESOURCE
--from result.json`; choose `--operation` when several are offered. Download an
original asset with `download ASSET --from result.json --variant VARIANT
--output-dir ./files`. Resource and asset IDs belong to that saved result; they
are not persistent account refs. Web cursors accept the returned token or
`--cursor @result.json` (its `pagination.next_cursor`), with the same source and
filters.

`read URL` recognizes supported Drive, Gmail, Calendar and Slack item URLs and
uses the connected account; use `--account` when ambiguous. Unsupported private
app URLs fail explicitly rather than entering public research. Public URLs use
the existing web reader. Web results preserve source-native pagination and
availability; a page of results is not proof of complete coverage.
