emcli/skills/emcli/AGENTIC-MANUAL.md

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 scripts/install.sh

If you only have this manual (pointed at the repo), fetch the installer first, then run it:

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.5.2	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):

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 agent key is present

emcli uses two keys; you (the agent) are given only EMCLI_KEY (the agent key). It authorises list, get, search, ack, send, and doctor. Admin commands require EMCLI_ADMIN_KEY, which the human holds — attempting admin commands with only EMCLI_KEY is refused by emcli.

For agent use, the orchestrator that launched you provides EMCLI_KEY 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 both keys with head -c 32 /dev/urandom | base64 (once per key) and store them securely; then run emcli init with both keys exported. 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). Discover the configured accounts yourself with emcli account list (an agent command authorised by EMCLI_KEY); it prints a JSON envelope with one entry per account:

emcli account list
# {"error":false,"error_detail":{},"data":{"accounts":[
#   {"name":"gmail","from":"me@gmail.com","can_send":true},
#   {"name":"alerts","from":"alerts@x.com","can_send":false}]}}

name is what you pass to --account; from is the send-as identity; can_send is false for read-only accounts (they reject send). If unsure which to use, ask the user. emcli doctor (also an agent command) checks that accounts connect and authenticate:

emcli doctor              # all accounts
emcli doctor --account gmail

Then 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.