diff --git a/README.md b/README.md index b926e4b..35546de 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![Go version](https://img.shields.io/badge/go-1.24-blue?logo=go)](https://golang.org/doc/go1.24) [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) -A command-line interface for the [SimpleLogin](https://simplelogin.io) email alias service. Manage aliases, contacts, mailboxes, domains, and settings directly from your terminal. +A command-line interface for the [SimpleLogin](https://simplelogin.io) email alias service. Manage aliases, contacts, mailboxes, domains, and settings directly from your terminal. For you and your agents. ## Installation @@ -70,6 +70,16 @@ sl auth login --1password --vault Personal --item "SimpleLogin API Key" This stores an `op://` reference in the config file. The actual key is fetched via the `op` CLI each time it's needed. You must have the [1Password CLI](https://developer.1password.com/docs/cli/) installed and signed in. +### Self-hosted instances + +If you run a self-hosted SimpleLogin instance, pass your URL at login: + +```bash +sl auth login --key sl_xxxxxxxxxxxxx --url https://sl.example.com +``` + +The URL is stored in the config file and used for all subsequent API calls. + ### Verify authentication ```bash @@ -78,7 +88,7 @@ sl auth status ### Get your API key -1. Go to https://app.simplelogin.io/dashboard/setting +1. Go to https://app.simplelogin.io/dashboard/setting (or your self-hosted URL) 2. Scroll to the "API Key" section 3. Generate or copy your API key @@ -97,8 +107,9 @@ sl alias list --all # View alias details sl alias view my-alias@simplelogin.co -# Toggle an alias on/off -sl alias toggle 12345 +# Enable/disable an alias (idempotent, safe for scripts) +sl alias enable 12345 +sl alias disable 12345 # Check account status sl account status @@ -106,55 +117,55 @@ sl account status ## Version -Check the installed version: - ```bash sl --version -# sl version v0.1.0 (abc1234, 2026-01-15T10:30:00Z) - -# or equivalently -sl version +# sl version 0.2.0 (abc1234, 2026-03-26T20:00:00Z) ``` -Binaries from the [Releases](https://github.com/mexcool/simplelogin-cli/releases) page and Homebrew include the version tag, commit hash, and build date. When installed via `go install` without explicit ldflags, the Go module version (e.g. `v0.1.0`) is shown if available; otherwise it falls back to `dev`. +Binaries from [Releases](https://github.com/mexcool/simplelogin-cli/releases) and Homebrew include the version tag, commit hash, and build date. When installed via `go install`, the Go module version is shown if available; otherwise it falls back to `dev`. ## Command Reference +Most commands support `--json` and `--jq` flags for machine-readable output. Many commands have short aliases (`ls`, `rm`, `info`) for convenience. + ### `sl auth` — Manage authentication | Command | Description | |---------|-------------| -| `sl auth login` | Authenticate with SimpleLogin | +| `sl auth login` | Authenticate interactively | | `sl auth login --key ` | Store API key directly | +| `sl auth login --key --url ` | Authenticate against a self-hosted instance | | `sl auth login --1password --vault --item ` | Use 1Password integration | | `sl auth logout` | Remove stored credentials | -| `sl auth status` | Show current user and masked key | +| `sl auth status` | Show current user, key source, and API URL | ### `sl alias` — Manage email aliases | Command | Description | |---------|-------------| -| `sl alias list` | List aliases (first page) | +| `sl alias list` (alias: `ls`) | List aliases (first page) | | `sl alias list --all` | List all aliases | -| `sl alias list --enabled` | List only enabled aliases | -| `sl alias list --disabled` | List only disabled aliases | -| `sl alias list --pinned` | List only pinned aliases | +| `sl alias list --enabled` / `--disabled` / `--pinned` | Filter aliases | | `sl alias list --query ` | Search aliases | -| `sl alias list --page ` | List specific page | +| `sl alias view ` (alias: `info`) | View alias details | | `sl alias create --random` | Create a random alias | -| `sl alias create --random --note ` | Create random alias with note | -| `sl alias create --prefix

` | Create custom alias (interactive suffix) | +| `sl alias create --random --mode word` | Create word-based random alias | +| `sl alias create --random --mode uuid` | Create UUID-based random alias | +| `sl alias create --random --hostname github.com` | Associate alias with a website | | `sl alias create --prefix

--suffix ` | Create custom alias with specific suffix | -| `sl alias create --prefix

--mailbox ` | Create alias assigned to mailbox | -| `sl alias view ` | View alias details | -| `sl alias delete ` | Delete an alias | -| `sl alias delete --yes` | Delete without confirmation | -| `sl alias toggle ` | Enable/disable an alias | +| `sl alias create --prefix

--mailbox ` | Create alias assigned to mailbox(es) | +| `sl alias options` | Show available suffixes and creation options | +| `sl alias options --hostname github.com` | Show options tailored for a hostname | +| `sl alias enable ` | Ensure alias is enabled (idempotent) | +| `sl alias disable ` | Ensure alias is disabled (idempotent) | +| `sl alias toggle ` | Flip alias enabled/disabled state | | `sl alias edit --name ` | Set display name | | `sl alias edit --note ` | Set note | -| `sl alias edit --pin` | Pin alias | -| `sl alias edit --unpin` | Unpin alias | -| `sl alias edit --mailbox ` | Set mailbox | +| `sl alias edit --pin` / `--unpin` | Pin/unpin alias | +| `sl alias edit --mailbox ` | Set mailbox(es) | +| `sl alias delete ` (alias: `rm`) | Delete an alias (with confirmation) | +| `sl alias delete --yes` | Delete without confirmation | +| `sl alias delete --dry-run` | Preview what would be deleted | | `sl alias activity ` | View activity log | | `sl alias activity --all` | View all activity | @@ -162,20 +173,24 @@ Binaries from the [Releases](https://github.com/mexcool/simplelogin-cli/releases | Command | Description | |---------|-------------| -| `sl contact list ` | List contacts for an alias | +| `sl contact list ` (alias: `ls`) | List contacts for an alias | | `sl contact list --all` | List all contacts | | `sl contact add ` | Add contact (creates reverse alias) | -| `sl contact delete ` | Delete a contact | -| `sl contact toggle ` | Block/unblock a contact | +| `sl contact delete ` (alias: `rm`) | Delete a contact | +| `sl contact delete --dry-run` | Preview deletion | +| `sl contact block ` | Ensure contact is blocked (idempotent) | +| `sl contact unblock ` | Ensure contact is unblocked (idempotent) | +| `sl contact toggle ` | Flip block/unblock state | ### `sl mailbox` — Manage mailboxes | Command | Description | |---------|-------------| -| `sl mailbox list` | List all mailboxes | +| `sl mailbox list` (alias: `ls`) | List all mailboxes | | `sl mailbox add ` | Add a new mailbox | -| `sl mailbox delete ` | Delete a mailbox | +| `sl mailbox delete ` (alias: `rm`) | Delete a mailbox | | `sl mailbox delete --transfer-to ` | Delete and transfer aliases | +| `sl mailbox delete --dry-run` | Preview deletion | | `sl mailbox edit --default` | Set as default mailbox | | `sl mailbox edit --email ` | Change mailbox email | | `sl mailbox edit --cancel-change` | Cancel pending email change | @@ -184,12 +199,12 @@ Binaries from the [Releases](https://github.com/mexcool/simplelogin-cli/releases | Command | Description | |---------|-------------| -| `sl domain list` | List custom domains | -| `sl domain edit --catch-all` | Enable catch-all | -| `sl domain edit --no-catch-all` | Disable catch-all | -| `sl domain edit --random-prefix` | Enable random prefix | -| `sl domain edit --no-random-prefix` | Disable random prefix | +| `sl domain list` (alias: `ls`) | List custom domains | +| `sl domain view ` | View domain details (verification, mailboxes, alias count) | +| `sl domain edit --catch-all` / `--no-catch-all` | Toggle catch-all | +| `sl domain edit --random-prefix` / `--no-random-prefix` | Toggle random prefix | | `sl domain edit --name ` | Set display name | +| `sl domain edit --mailbox ` | Assign mailbox(es) to domain | | `sl domain trash ` | View deleted aliases | ### `sl setting` — Manage account settings @@ -219,14 +234,32 @@ Binaries from the [Releases](https://github.com/mexcool/simplelogin-cli/releases | `sl export aliases` | Export aliases as CSV | | `sl export aliases --output ` | Export to file | +### `sl completion` — Shell completions + +| Command | Description | +|---------|-------------| +| `sl completion bash` | Generate bash completions | +| `sl completion zsh` | Generate zsh completions | +| `sl completion fish` | Generate fish completions | +| `sl completion powershell` | Generate PowerShell completions | + ## Environment Variables | Variable | Description | |----------|-------------| | `SIMPLELOGIN_API_KEY` | API key (highest priority) | | `SL_API_KEY` | API key (alternative) | +| `SL_VERBOSE` or `SL_DEBUG` | Set to `1` to log HTTP requests to stderr | | `NO_COLOR` | Set to any value to disable colored output | +## Global Flags + +| Flag | Description | +|------|-------------| +| `--verbose` | Log HTTP requests to stderr (method, URL, status, latency) | +| `--json` | Output as JSON (available on most commands) | +| `--jq ` | Apply jq expression to JSON output | + ## Output Formats ### Default (table) @@ -261,16 +294,17 @@ sl mailbox list --json --jq '.mailboxes[] | select(.default) | .email' ## Agent Usage -This CLI is designed for both human and programmatic use. Every list/view command supports `--json` and `--jq` flags for machine-readable output. +This CLI is designed for both human and programmatic use. + +**Idempotent operations**: Use `sl alias enable`/`disable` and `sl contact block`/`unblock` instead of `toggle` — they check the current state first and are safe to call repeatedly. -**Progressive disclosure**: Every command has rich `--help` text with: -- `Short`: One-line description (shown in parent help) -- `Long`: Detailed explanation with context and behavior notes -- `Example`: Real usage examples +**Exit codes**: `0` for success, `1` for runtime errors, `2` for usage errors (wrong arguments/flags). Scripts can distinguish "bad invocation" from "API failure." -This makes the CLI self-documenting — agents and scripts can discover capabilities by reading help text. +**Self-documenting errors**: Error messages include actionable guidance, e.g., "invalid contact ID: use 'sl contact list ' to find IDs." -**Piping-friendly**: Success/status messages go to stderr, data goes to stdout. This means you can safely pipe output: +**Progressive disclosure**: Every command has rich `--help` text with examples. Agents can discover capabilities by reading help text. + +**Piping-friendly**: Status messages go to stderr, data goes to stdout: ```bash # Create alias and capture just the email @@ -280,16 +314,26 @@ NEW_ALIAS=$(sl alias create --random 2>/dev/null) sl export data | jq '.aliases | length' ``` +**Debugging**: Use `--verbose` or `SL_VERBOSE=1` to see HTTP requests without exposing API keys. + ## Configuration Config file location: `$XDG_CONFIG_HOME/simplelogin/config.yml` (defaults to `~/.config/simplelogin/config.yml`) ```yaml api_key: sl_xxxxxxxxxxxxx +api_base: https://sl.example.com # only for self-hosted instances # or for 1Password: op_ref: op://Personal/SimpleLogin API Key/credential ``` +## Related Projects + +Other community-built SimpleLogin CLIs: + +- [KennethWussmann/simplelogin-cli](https://github.com/KennethWussmann/simplelogin-cli) — TypeScript/oclif, includes a separate SDK library. +- [joedemcher/simplelogin-cli](https://github.com/joedemcher/simplelogin-cli) — Python/docopt, available on PyPI. Rich interactive prompts with questionary. + ## Disclaimer This is an unofficial, community-developed CLI tool and is not affiliated with, endorsed by, or supported by SimpleLogin or Proton AG. SimpleLogin is a trademark of Proton AG. Please direct any issues with this tool to [this repository's issue tracker](https://github.com/mexcool/simplelogin-cli/issues), not to SimpleLogin support.