steve/emcli
1
0
Fork 0
Code Issues Pull Requests Actions Projects Releases 4 Wiki Activity

docs(skill): split setup into AGENTIC-MANUAL.md; keep SKILL.md lean

Browse Source 
The SKILL.md body loads into context on every activation, so one-time install/
setup prose was wasted context once emcli is running. Move it out:

- New AGENTIC-MANUAL.md: get-the-files bootstrap, binary install (incl. options
  and build-from-source, folding in the old references/install.md), EMCLI_KEY,
  account discovery. Fetched only during first-time setup.
- SKILL.md trimmed (182→~145 lines) to the recurring path: security model, a short
  "Files & first run" pointer + per-session preflight, the list/get/ack/send
  workflow, JSON envelope, command table, enforcement, do/don't.
- Remove references/install.md (folded in); fix RELEASING.md pointer.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Steve Cliff
2026-06-22 21:01:46 +01:00
parent 93dbebb982
commit 7087533644
4 changed files with 115 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files
RELEASING.md
+2 -2
View File
@@ -49,8 +49,8 @@ published. If it ever doesn't fit your runner setup, fall back to Option A.
## After a release ## After a release
The skill installer defaults to `EMCLI_VERSION=v0.4.0`. When you cut a different version, either The skill installer defaults to `EMCLI_VERSION=v0.4.0`. When you cut a different version, either
publish under that tag or update the default in `skills/emcli/scripts/install.sh` (and the note in publish under that tag or update the default in `skills/emcli/scripts/install.sh` (and the options
`skills/emcli/references/install.md`). table in `skills/emcli/AGENTIC-MANUAL.md`).
## Versioning ## Versioning
skills/emcli/AGENTIC-MANUAL.md
+99
View File
@@ -0,0 +1,99 @@
# emcli — setup manual (for agents)
Read this **once**, when emcli isn't set up yet (the binary isn't installed, or you only have
`SKILL.md` from being pointed at the repo). The recurring "how to read and send mail" lives in
`SKILL.md` — don't reload this file for normal use.
## 1. Get this skill's files
This skill is a folder, not a single file: it ships `AGENTIC-MANUAL.md` (this file), a `scripts/`
directory, and a `references/` directory. If you were pointed at the repository and have only
`SKILL.md` in context, fetch what you need before proceeding.
Every `scripts/…` and `references/…` path mentioned anywhere in this skill is **relative to the
skill directory**, whose raw base URL is:
```
https://gitea.dcglab.co.uk/steve/emcli/raw/branch/main/skills/emcli/
```
So a file that isn't already on disk can be fetched from `<base>/<path>`. The files are:
| Path | Purpose |
|---|---|
| `SKILL.md` | The lean, everyday usage guide |
| `AGENTIC-MANUAL.md` | This setup guide (one-time) |
| `scripts/install.sh` | Installs the emcli binary |
| `references/commands.md` | Full agent command reference (flags, JSON shapes, error codes) |
To enumerate the directory programmatically (then recurse into `scripts` and `references`), use the
Gitea contents API: `https://gitea.dcglab.co.uk/api/v1/repos/steve/emcli/contents/skills/emcli`.
## 2. Install the binary
First check whether it's already installed: `emcli version`. If that prints a version, skip to
step 3.
If you have the skill files locally:
```bash
bash scripts/install.sh
```
If you only have this manual (pointed at the repo), fetch the installer first, then run it:
```bash
curl -fsSL https://gitea.dcglab.co.uk/steve/emcli/raw/branch/main/skills/emcli/scripts/install.sh -o emcli-install.sh
bash emcli-install.sh
```
`install.sh` detects your OS/arch, downloads the matching release binary, verifies its SHA-256
checksum, makes it executable in `~/.local/bin` (ensure that's on your PATH), and confirms it runs.
**Installer options** (environment variables):
| Variable | Default | Purpose |
|---|---|---|
| `EMCLI_VERSION` | `v0.4.0` | Release tag to fetch |
| `EMCLI_BASE_URL` | `https://gitea.dcglab.co.uk/steve/emcli` | Repo base URL |
| `EMCLI_INSTALL_DIR` | `$HOME/.local/bin` | Install location |
**Build from source instead** (needs Go; the binary is CGO-free):
```bash
git clone https://gitea.dcglab.co.uk/steve/emcli && cd emcli
CGO_ENABLED=0 go build -o emcli ./cmd/emcli # then move ./emcli onto your PATH
```
## 3. Confirm the encryption key is present
emcli needs `EMCLI_KEY` (a base64-encoded 32-byte AES key) to touch its database. For agent use,
**the orchestrator that launched you provides it** in the environment.
- Confirm it's set, without printing it: `test -n "$EMCLI_KEY" && echo present`.
- **Never** read, print, log, pass as an argument, or generate this value.
- If it's empty, stop and tell the user: "emcli needs the `EMCLI_KEY` environment variable set by
your orchestrator; I can't read or create it for you."
(For a human setting emcli up the first time: generate one with `head -c 32 /dev/urandom | base64`
and store it securely. Account creation and other admin is the human's job — see the project's
`USER-MANUAL.md`.)
## 4. Find the account(s)
You refer to an account by name (e.g. `gmail`, `work`). Ask the user which account to use. If the
user permits running admin commands, `emcli doctor` lists the configured accounts and checks that
each one connects and authenticates:
```bash
emcli doctor # all accounts
emcli doctor --account gmail
```
Otherwise, just take the account name from the user and start with the workflow in `SKILL.md`.
## You're set up
Installed, key present, account name in hand → switch to `SKILL.md` for the everyday `list` / `get`
/ `search` / `ack` / `send` workflow. You shouldn't need this manual again unless the binary goes
missing.
skills/emcli/SKILL.md
+14 -51
View File
@@ -15,31 +15,6 @@ and send mail; the program holds the credentials and enforces the user's rules,
password and cannot bypass the limits. Every agent command prints exactly **one line of JSON** and password and cannot bypass the limits. Every agent command prints exactly **one line of JSON** and
sets its exit code to match. sets its exit code to match.
## First: get this skill's files
This skill is more than this one file. It ships a `scripts/` and a `references/` directory that the
steps below use. **If you were pointed at the repository and have only this `SKILL.md` in context,
download the rest of the skill's files before proceeding** — fetch the whole `skills/emcli/`
directory, or grab each file as a step calls for it.
Every `scripts/…` and `references/…` path mentioned in this document is **relative to this skill's
directory**. If a file isn't already on disk, fetch it from this raw base URL + the path:
```
https://gitea.dcglab.co.uk/steve/emcli/raw/branch/main/skills/emcli/
```
The files are:
| Path | Purpose |
|---|---|
| `scripts/install.sh` | Installs the emcli binary |
| `references/commands.md` | Full agent command reference (flags, JSON shapes, error codes) |
| `references/install.md` | Installer options / build from source |
To enumerate the directory programmatically (then recurse into `scripts` and `references`), use the
Gitea contents API: `https://gitea.dcglab.co.uk/api/v1/repos/steve/emcli/contents/skills/emcli`.
## Security model — read this first ## Security model — read this first
- **You only run agent commands:** `list`, `get`, `search`, `ack`, `send`. Account setup, - **You only run agent commands:** `list`, `get`, `search`, `ack`, `send`. Account setup,
@@ -48,39 +23,27 @@ Gitea contents API: `https://gitea.dcglab.co.uk/api/v1/repos/steve/emcli/content
to help administer. to help administer.
- **Never touch the secret key.** `EMCLI_KEY` is supplied in the environment by whoever launched - **Never touch the secret key.** `EMCLI_KEY` is supplied in the environment by whoever launched
you. Do not read it, print it, log it, pass it as an argument, or try to generate one. If it is you. Do not read it, print it, log it, pass it as an argument, or try to generate one. If it is
missing, stop and tell the user (see Setup). missing, stop and tell the user (see "Files & first run").
- **Some mail is intentionally invisible.** The user may restrict which senders you can see and who - **Some mail is intentionally invisible.** The user may restrict which senders you can see and who
you can email. Blocked or filtered results are normal — handle them, don't try to work around you can email. Blocked or filtered results are normal — handle them, don't try to work around
them (see Enforcement). them (see Enforcement).
## Setup (do this once per session, before the first command) ## Files & first run
1. **Check the binary is available.** Run `emcli version`. If the command is not found, install it. This skill ships more than this file. Paths like `AGENTIC-MANUAL.md` and `references/commands.md`
are relative to this skill's directory; if one isn't on disk, fetch it from the raw base URL + path:
If you have the skill files locally: ```
https://gitea.dcglab.co.uk/steve/emcli/raw/branch/main/skills/emcli/
```
```bash - **First-time setup** — installing the binary, the `EMCLI_KEY`, finding accounts: read
bash scripts/install.sh **`AGENTIC-MANUAL.md`**. Only needed when emcli isn't set up yet.
``` - **Full command detail** — every flag, JSON shapes, error codes: `references/commands.md`.
If you only have this `SKILL.md` (pointed at the repo), fetch the installer first, then run it: **Per-session preflight** (quick): run `emcli version`; if it's not found, set up via
`AGENTIC-MANUAL.md`. Confirm `EMCLI_KEY` is set *without printing it* (`test -n "$EMCLI_KEY"`); if
```bash empty, tell the user their orchestrator must provide it. Then get the account name from the user.
curl -fsSL https://gitea.dcglab.co.uk/steve/emcli/raw/branch/main/skills/emcli/scripts/install.sh -o emcli-install.sh
bash emcli-install.sh
```
This downloads the binary from the project's releases and puts it on your PATH
(`~/.local/bin` by default). For options, see `references/install.md` (fetch it from the raw base
URL above if you don't have it locally).
2. **Check the key is present.** Confirm the `EMCLI_KEY` environment variable is set (e.g.
`test -n "$EMCLI_KEY"`). **Do not print its value.** If it is empty, do not proceed — tell the
user: "emcli needs the EMCLI_KEY environment variable set by your orchestrator; I can't read or
create it for you."
3. **Find out which account(s) exist.** Ask the user for the account name (e.g. `gmail`, `work`),
or, if permitted, run `emcli doctor` once to see configured accounts and that they connect.
## How to read every result ## How to read every result
@@ -160,7 +123,7 @@ Defaults: `--folder INBOX`, `--limit 50` (max 500). Dates are RFC 3339 (e.g.
**Full reference** (every flag, exact JSON shapes for each command, attachment encoding, error **Full reference** (every flag, exact JSON shapes for each command, attachment encoding, error
codes, and the enforcement rules): `references/commands.md` — read it from disk, or fetch it from codes, and the enforcement rules): `references/commands.md` — read it from disk, or fetch it from
the raw base URL in "First: get this skill's files" above if you don't have it locally. the raw base URL in "Files & first run" above if you don't have it locally.
## Enforcement awareness — work *with* the rules ## Enforcement awareness — work *with* the rules
skills/emcli/references/install.md
-62
View File
@@ -1,62 +0,0 @@
# Installing the emcli binary
The skill's `scripts/install.sh` downloads a prebuilt binary from the project's release assets.
## Quick install
```bash
bash scripts/install.sh
```
It detects your OS (`linux`/`darwin`/`windows`) and architecture (`amd64`/`arm64`), downloads the
matching asset, verifies its SHA-256 checksum when a `checksums.txt` is published, makes it
executable, and confirms it runs.
## Options (environment variables)
| Variable | Default | Purpose |
|---|---|---|
| `EMCLI_VERSION` | `v0.4.0` | Release tag to fetch |
| `EMCLI_BASE_URL` | `https://gitea.dcglab.co.uk/steve/emcli` | Repo base URL |
| `EMCLI_INSTALL_DIR` | `$HOME/.local/bin` | Install location |
Example — install a specific version to a system directory:
```bash
EMCLI_VERSION=v0.4.0 EMCLI_INSTALL_DIR=/usr/local/bin bash scripts/install.sh
```
## Release asset naming
The release publishes one binary per platform plus a checksum file:
```
emcli_0.4.0_linux_amd64
emcli_0.4.0_linux_arm64
emcli_0.4.0_darwin_amd64
emcli_0.4.0_darwin_arm64
emcli_0.4.0_windows_amd64.exe
checksums.txt # sha256, one "<sum> <asset>" line per asset
```
> `v0.4.0` and these assets are placeholders until the first tagged release exists. Update
> `EMCLI_VERSION` (or the default in `install.sh`) once a real release is cut.
## Building from source instead
If you have Go and prefer to build rather than download:
```bash
git clone https://gitea.dcglab.co.uk/steve/emcli
cd emcli
CGO_ENABLED=0 go build -o emcli ./cmd/emcli
# then move ./emcli onto your PATH
```
## After installing
`emcli` needs the `EMCLI_KEY` environment variable (a base64-encoded 32-byte AES key) to touch its
database. For agent use, the **orchestrator provides this** — the agent should not generate or read
it. A human setting up emcli for the first time generates one with
`head -c 32 /dev/urandom | base64` and saves it securely. See the project User Manual for full admin
setup.