eppie-io/eppie-cli/docs

Eppie CLI agent skill

Use this skill when an autonomous or semi-autonomous agent must operate eppie-console directly.

eppie-console is a console mail client that can work with:

• Gmail,
• Outlook,
• Proton Mail,
• regular IMAP/SMTP email services,
• decentralized peer-to-peer Eppie mail.

Purpose

Use eppie-console in a predictable, automation-friendly way to:

• inspect accounts,
• inspect folders,
• read messages,
• send messages,
• sync folders,
• initialize, unlock, and reset the local vault when needed by the task.

This skill focuses on deterministic command execution, structured output handling, and explicit standard-input contracts.

For end-to-end validation, coverage, and reproducible test scenarios, use eppie-cli-agent-test-plan.md.

How to use this file

Treat sections marked Normative as the required contract for agent execution. Treat sections marked Reference as supporting material, examples, or quick navigation aids.

Normative sections in this file:

• Normative defaults for agents
• Normative rules
• Normative command patterns for agents
• Normative stdin contracts
• Normative execution policy for autonomous agents
• Normative error handling

Reference sections in this file:

• Reference: preferred installation
• Reference: required inputs
• Reference: launch modes
• Reference: decision guide
• Reference: end-to-end agent scenarios
• Reference: command-specific notes and examples
• Reference: recommended agent workflow
• Reference: known limitations
• Reference: contributing

Normative defaults for agents

When the task requires executing eppie-console, use these defaults unless the task explicitly requires otherwise:

1. use --non-interactive=true
2. use --output=json for agent automation unless text output is explicitly required
3. use --unlock-password-stdin=true for stateful commands that need an existing vault
4. use --assume-yes=true for destructive automation
5. provide stdin exactly in the required order
6. use one consistent working directory per vault

Canonical command patterns and exact stdin contracts are defined later in this file. Use those sections as the single source of truth for agent execution.

Use this skill when

• the task requires executing eppie-console
• the agent must inspect accounts, folders, messages, or contacts
• the agent must send a message
• the agent must synchronize a folder
• the agent must initialize or reset the local vault
• the agent must work with machine-readable CLI output

Do not use this skill when

• the task does not require calling eppie-console
• the task is only to explain behavior conceptually without running commands
• the task is primarily about test coverage or validation workflows; use eppie-cli-agent-test-plan.md
• an interactive REPL session is not explicitly required but would be the only execution path
• the required executable or working directory is unavailable

Reference: preferred installation

Prefer the executable published in GitHub Releases. You can also build from source.

Latest release page:

• https://github.com/Eppie-io/Eppie-CLI/releases/latest

Direct download links:

Linux

• https://github.com/Eppie-io/Eppie-CLI/releases/latest/download/Eppie.CLI-linux-x64.tar.gz
• https://github.com/Eppie-io/Eppie-CLI/releases/latest/download/Eppie.CLI-linux-arm64.tar.gz

macOS

• https://github.com/Eppie-io/Eppie-CLI/releases/latest/download/Eppie.CLI-osx-x64.tar.gz
• https://github.com/Eppie-io/Eppie-CLI/releases/latest/download/Eppie.CLI-osx-arm64.tar.gz

Windows

• https://github.com/Eppie-io/Eppie-CLI/releases/latest/download/Eppie.CLI-win-x64.zip
• https://github.com/Eppie-io/Eppie-CLI/releases/latest/download/Eppie.CLI-win-arm64.zip

After extracting the archive, use the eppie-console executable directly.

Reference: required inputs

Common inputs

• path to eppie-console
• working directory
• whether the task requires stateful access to an existing vault
• whether structured JSON output is required

Vault access inputs

• vault password
• whether the vault must be initialized first

Reading inputs

• account identifier for -a; for agent workflows, use the account address string returned by list-accounts in data[].address
• folder name when folder-specific access is needed
• message id
• message pk
• page size and total limit for paged commands

Sending inputs

• sender address
• receiver address
• subject
• message body

Account creation inputs

• account type
• vault password
• structured JSON payload when required
• provider-specific secrets only through standard input when supported

Reference: launch modes

Interactive mode

Use only when a REPL session is explicitly needed.

Example:

• eppie-console

Typical sequence:

• open
• vault password
• list-accounts
• exit

open is useful in interactive mode to open the local vault inside the current process.

Non-interactive mode

Prefer this mode for agents.

Use:

• eppie-console --non-interactive=true <command> [command options]

To avoid passing the same startup flags on every call, you can put them in appsettings.json next to eppie-console, for example:

• { "non-interactive": true, "output": "json", "unlock-password-stdin": true }

eppie-console also reads configuration from environment variables.

When the default .NET host configuration pipeline is used, environment variables override appsettings.json. Command-line arguments override both.

For structured machine-readable output, also use:

• --output=json

JSON responses use a normalized envelope:

• type: result, status, warning, or error
• code: stable machine-readable outcome code
• data: payload for result and status responses
• meta: optional metadata for result responses; usually null, but paged read commands can return objects such as {"header":"All messages:","returned":5,"hasMore":true}
• message: human-readable warning/error text

In --non-interactive=true --output=json mode, structured responses are emitted on stdout without a preceding stack trace on stderr for handled command failures such as unhandledException.

In that mode the prompts are gone, so before each value it reads as a single line the run emits {"type":"status","code":"inputRequired","data":{"input":"<name>"}}, naming the value being read. A command therefore emits several envelopes even in the ordinary case: parse stdout line by line and act on the last one. Text output carries no announcements. The message body of send is the exception: it is read to end-of-stream rather than as a single line and is not announced, so write it straight after the vault password and close stdin.

data.input is one of nine names: vaultPassword for any run with --unlock-password-stdin=true and for open; newVaultPassword for init and restore; seedPhrase and restorePath for restore; accountAddress and accountPassword for add-account -t proton without --input-json-stdin, followed in that same run by twoFactorCode, mailboxPassword and humanVerificationToken whenever Proton asks for them. Nothing else is announced -- add-account -t email takes its values as one payload or refuses, and a vault password is never confirmed in this mode.

--output=json requires --non-interactive=true. Reading from a console writes the prompt and the typed characters to stdout, which cannot share the stream with the envelopes, so the run is refused with interactiveInputNotSupported and exit code 1 before any command starts, leaving nothing half-done.

In non-interactive mode, do not use open as part of the agent workflow. It does not establish reusable state for later process launches. For stateful non-interactive commands, use --unlock-password-stdin=true instead.

For all agent examples in this file, <account> means the account address returned by list-accounts in data[].address. Prefer that address string for -a instead of the numeric id, unless a command explicitly documents another identifier format.

Common success-output examples:

• --non-interactive=true --output=json list-accounts (with accounts):
• {"type":"result","code":"accounts","data":[{"id":1,"address":"<address>","accountType":"Dec"}],"meta":null}
• --non-interactive=true --assume-yes=true --output=json reset:
• {"type":"status","code":"reset","data":null}
• --non-interactive=true --unlock-password-stdin=true --output=json send ...:
• {"type":"status","code":"messageSent","data":{"subject":"<subject>","to":"<receiver>","from":"<sender>"}}
• --non-interactive=true --unlock-password-stdin=true --output=json sync-folder ...:
• {"type":"status","code":"folderSynced","data":{"account":"<account>","folder":"Inbox"}}
• --non-interactive=true --unlock-password-stdin=true --output=json show-all-messages ...:
• {"type":"result","code":"messages","data":[{"id":1,"pk":1,"to":["<receiver>"],"from":["<sender>"],"folder":"Inbox","subject":"<subject>"}],"meta":{"header":"All messages:","returned":1,"hasMore":false}}

Additional command-specific JSON result shapes are documented later in Reference: command-specific notes and examples.

Common text success-output examples:

• open:
• The application was opened successfully.
• reset:
• The application has just been reset.
• add-account -t dec:
• Account <generated-address> added (Dec).
• send:
• Message sent from <sender> to <receiver>. Subject: <subject>
• sync-folder -f Inbox:
• Folder 'Inbox' for account <account> synchronized.

Normative rules

• Treat Normative command patterns for agents and Normative stdin contracts as normative for agent workflows.
• Put global launch options before -- and put the startup command after --.
• Do not assume open creates a reusable session for future process launches.
• Synchronize the relevant folder before reading when the task requires newly arrived messages.
• Do not guess provider-specific folder names; call list-folders first.
• Use -l / --limit when predictable payload size matters.
• Do not pass account secrets in command-line arguments when structured standard input is supported.

eppie-console open only opens the vault inside the current process. It does not create a reusable session for future process launches.

Normative command patterns for agents

Use this section as the single source of truth for agent command lines. Unless text output is explicitly required, all agent examples below use --output=json.