@ketrwu/simplelogin-cli

v0.2.2

Published

5 months ago

Unofficial SimpleLogin CLI

0High
0Medium
0Low

simplelogin api cli client sdk rest simplelogin.io

SimpleLogin is an e-mail aliasing service by Proton. This is a third-party CLI tool using simplelogin-client under the hood.

Installation

Installing the CLI is done via the Node Package Manager.

## Install with NPM
$ npm install -g @ketrwu/simplelogin-cli

## or install with PNPM
$ pnpm add -g @ketrwu/simplelogin-cli
...

Usage

Requires a SimpleLogin API key

The CLI provides a streamlined interface for managing your SimpleLogin aliases directly from the terminal. All commands support multiple output formats and are designed for both interactive use and automation.

## 1. Authenticate with your SimpleLogin account
$ sl login
? Enter SimpleLogin URL (default: https://app.simplelogin.io):
? Enter your API key: ************************************

## 2. Create aliases on-demand
$ sl alias create --note "Newsletter subscriptions"
Alias created successfully
ID:      245
Email:   [email protected]
Enabled: true
Mailboxes: [email protected]

## 3. Search and filter your aliases
$ sl alias search "github" --enabled
ID      Email                                   Enabled   Pinned    Mailboxes
----------------------------------------------------------------------------------------------------
10      [email protected]                      Yes       No        [email protected]

Total: 1 alias

## 4. Create custom aliases with specific prefixes. Note that you have to use a suffix ([email protected]) from the "sl alias options"
$ sl alias custom netflix [email protected] --note "Streaming services"
Alias created successfully
ID:      246
Email:   [email protected]
Enabled: true
Mailboxes: [email protected]

## 5. View configuration and verify authentication
$ sl whoami
Email:   [email protected]
Name:    Sarah Chen
Premium: true

## 6. Access comprehensive help for any command
$ sl alias create --help

Automation & Scripting

The true power of simplelogin-cli lies in its automation capabilities. Every command supports structured output formats (json, yaml, plain), making it seamless to integrate SimpleLogin into your workflows, scripts, and toolchains.

Why This Matters

Password Manager Integration: Automatically generate unique aliases during account registration workflows
Batch Operations: Process, filter, or modify hundreds of aliases programmatically
CI/CD Pipelines: Provision aliases for testing environments or service accounts
Monitoring & Analytics: Extract alias metrics and usage patterns
Cross-Tool Integration: Pipe data between sl and other CLI tools like jq, fzf, or custom scripts

Output Format Control

Every command accepts the --format flag to control output structure:

## Human-readable output (default)
$ sl alias ls --page 0
ID      Email                                   Enabled   Pinned    Mailboxes
----------------------------------------------------------------------------------------------------
100     [email protected]                     Yes       No        [email protected]
101     [email protected]                     Yes       No        [email protected]
102     [email protected]                        Yes       No        [email protected]

Total: 3 aliases

## JSON for programmatic processing
$ sl alias ls --page 0 --format json
[
  {
    "id": 100,
    "email": "[email protected]",
    // ...
  },
  {
    "id": 101,
    "email": "[email protected]",
    // ...
  },
  {
    "id": 102,
    "email": "[email protected]",
    // ...
  }
]

## YAML for configuration or human-readable structured data
$ sl alias ls --page 0 --format yaml

Practical Automation Examples

Extract All Alias Emails

Transform alias data with jq for downstream processing:

$ sl alias ls --all --format json | jq -r 'map(.email) | .[]'
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]

Automated Alias Generation Script

Create service-specific aliases programmatically. This example demonstrates fetching available options and creating a custom alias in a single workflow:

generate-alias.sh

#!/bin/bash
set -euo pipefail

# Configuration
SERVICE_NAME="${1:?Usage: $0 <service-name>}"
DOMAIN="example.com"
NOTE="${2:-Auto-generated for $SERVICE_NAME}"

# Fetch available signed suffix for the domain
echo "Fetching alias options for domain: $DOMAIN"
SUFFIX=$(sl alias options --domain "$DOMAIN" --prefix --format json | jq -r '.suffixes[0].signedSuffix')

if [ -z "$SUFFIX" ]; then
  echo "Error: No valid suffix found for domain $DOMAIN" >&2
  exit 1
fi

# Create the alias
echo "Creating alias: ${SERVICE_NAME}${SUFFIX}"
sl alias custom "$SERVICE_NAME" "$SUFFIX" --note "$NOTE" --format json

echo "✓ Alias created successfully!"

Usage:

$ ./generate-alias.sh spotify "Music streaming service"
✓ Alias created successfully!

Filter and Export Specific Aliases

Extract aliases matching specific criteria for reporting or backup:

#!/bin/bash
# Export all enabled aliases to a CSV file

echo "id,email,note" > aliases_backup.csv
sl alias ls --all --enabled --format json | \
  jq -r '.[] | [.id, .email, .note] | @csv' >> aliases_backup.csv

echo "✓ Backup complete: aliases_backup.csv"

Output:

id,email,note
198,"[email protected]","Development notifications"
203,"[email protected]","Sponsorship updates"
245,"[email protected]","Newsletter subscriptions"
246,"[email protected]","Streaming services"
247,"[email protected]","Music streaming service"

Password Manager Integration

Integrate with password managers to automatically generate unique aliases during account creation:

#!/bin/bash
# Create account with unique alias in 1Password
SERVICE="Spotify Premium"
NOTE="Music streaming service"

# Generate a new alias
ALIAS_EMAIL=$(sl alias create --mode word --note "$NOTE" --format json | jq -r '.email')

# Create password manager entry with the alias
op item create --category=login \
  --title="$SERVICE" \
  --username="$ALIAS_EMAIL" \
  --password="$(op generate --length=32)"

echo "✓ Created $SERVICE account with alias: $ALIAS_EMAIL"

Integration Benefits

The CLI's structured output enables integration with:

Password Managers: 1Password, Bitwarden, pass, KeePassXC
Terminal Tools: fzf (fuzzy finder), rofi (application launcher)
Automation Frameworks: Ansible, Terraform, custom deployment scripts
Monitoring Systems: Export metrics, track alias usage
Development Workflows: Pre-commit hooks, test environment setup

Commands

`sl alias create`

Create a new random alias

USAGE
  $ sl alias create [--config <value>] [--format plain|json|yaml] [--note <value>] [--hostname <value>] [--mode
    uuid|word]

FLAGS
  --config=<value>    [env: SIMPLELOGIN_CONFIG] Path to config file containing credentials
  --format=<option>   [default: plain] Output format
                      <options: plain|json|yaml>
  --hostname=<value>  Associated hostname
  --mode=<option>     Generation mode (uuid or word-based)
                      <options: uuid|word>
  --note=<value>      Note/description for the alias

DESCRIPTION
  Create a new random alias

EXAMPLES
  $ sl alias create

  $ sl alias create --note "My test alias"

  $ sl alias create --hostname example.com

  $ sl alias create --mode uuid

  $ sl alias create --mode word --note "Shopping" --format json

See code: src/commands/alias/create.ts

`sl alias create-custom PREFIX SUFFIX`

Create a custom alias with specific prefix and suffix

USAGE
  $ sl alias create-custom PREFIX SUFFIX [--config <value>] [--format plain|json|yaml] [--note <value>] [--hostname
    <value>] [--mailbox-ids <value>] [--name <value>]

ARGUMENTS
  PREFIX  Alias prefix (local part)
  SUFFIX  Signed suffix from alias options

FLAGS
  --config=<value>       [env: SIMPLELOGIN_CONFIG] Path to config file containing credentials
  --format=<option>      [default: plain] Output format
                         <options: plain|json|yaml>
  --hostname=<value>     Associated hostname
  --mailbox-ids=<value>  Comma-separated mailbox IDs. Default if not specified.
  --name=<value>         Display name
  --note=<value>         Note/description for the alias

DESCRIPTION
  Create a custom alias with specific prefix and suffix

ALIASES
  $ sl alias custom

EXAMPLES
  $ sl alias create-custom myprefix signed_suffix --mailbox-ids 1,2

  $ sl alias create-custom john suffix123 --note "Work email to my default mailbox"

  $ sl alias create-custom support suffix456 --mailbox-ids 1 --name "Support" --hostname example.com

  $ sl alias create-custom custom suffix789 --mailbox-ids 1,2,3 --format json

See code: src/commands/alias/create-custom.ts

`sl alias custom PREFIX SUFFIX`

Create a custom alias with specific prefix and suffix

USAGE
  $ sl alias custom PREFIX SUFFIX [--config <value>] [--format plain|json|yaml] [--note <value>] [--hostname
    <value>] [--mailbox-ids <value>] [--name <value>]

ARGUMENTS
  PREFIX  Alias prefix (local part)
  SUFFIX  Signed suffix from alias options

FLAGS
  --config=<value>       [env: SIMPLELOGIN_CONFIG] Path to config file containing credentials
  --format=<option>      [default: plain] Output format
                         <options: plain|json|yaml>
  --hostname=<value>     Associated hostname
  --mailbox-ids=<value>  Comma-separated mailbox IDs. Default if not specified.
  --name=<value>         Display name
  --note=<value>         Note/description for the alias

DESCRIPTION
  Create a custom alias with specific prefix and suffix

ALIASES
  $ sl alias custom

EXAMPLES
  $ sl alias custom myprefix signed_suffix --mailbox-ids 1,2

  $ sl alias custom john suffix123 --note "Work email to my default mailbox"

  $ sl alias custom support suffix456 --mailbox-ids 1 --name "Support" --hostname example.com

  $ sl alias custom custom suffix789 --mailbox-ids 1,2,3 --format json

`sl alias delete ALIAS-ID`

Delete an alias by ID

USAGE
  $ sl alias delete ALIAS-ID [--config <value>] [--format plain|json|yaml] [--confirm]

ARGUMENTS
  ALIAS-ID  Alias ID to delete

FLAGS
  --config=<value>   [env: SIMPLELOGIN_CONFIG] Path to config file containing credentials
  --confirm          Skip confirmation prompt
  --format=<option>  [default: plain] Output format
                     <options: plain|json|yaml>

DESCRIPTION
  Delete an alias by ID

ALIASES
  $ sl alias rm

EXAMPLES
  $ sl alias delete 123

  $ sl alias delete 123 --confirm

  $ sl alias delete 123 --format json

  $ sl alias rm 123 --confirm

See code: src/commands/alias/delete.ts

`sl alias list`

List all aliases with pagination

USAGE
  $ sl alias list [--config <value>] [--format plain|json|yaml] [--page <value>] [--pinned | --disabled |
    --enabled] [--all]

FLAGS
  --all              Fetch all pages automatically
  --config=<value>   [env: SIMPLELOGIN_CONFIG] Path to config file containing credentials
  --disabled         Show only disabled aliases
  --enabled          Show only enabled aliases
  --format=<option>  [default: plain] Output format
                     <options: plain|json|yaml>
  --page=<value>     Page number (20 aliases per page)
  --pinned           Show only pinned aliases

DESCRIPTION
  List all aliases with pagination

ALIASES
  $ sl alias ls

EXAMPLES
  $ sl alias list

  $ sl alias list --page 1

  $ sl alias list --pinned

  $ sl alias list --disabled

  $ sl alias list --enabled

  $ sl alias list --all

  $ sl alias list --format json

See code: src/commands/alias/list.ts

`sl alias ls`

List all aliases with pagination

USAGE
  $ sl alias ls [--config <value>] [--format plain|json|yaml] [--page <value>] [--pinned | --disabled |
    --enabled] [--all]

FLAGS
  --all              Fetch all pages automatically
  --config=<value>   [env: SIMPLELOGIN_CONFIG] Path to config file containing credentials
  --disabled         Show only disabled aliases
  --enabled          Show only enabled aliases
  --format=<option>  [default: plain] Output format
                     <options: plain|json|yaml>
  --page=<value>     Page number (20 aliases per page)
  --pinned           Show only pinned aliases

DESCRIPTION
  List all aliases with pagination

ALIASES
  $ sl alias ls

EXAMPLES
  $ sl alias ls

  $ sl alias ls --page 1

  $ sl alias ls --pinned

  $ sl alias ls --disabled

  $ sl alias ls --enabled

  $ sl alias ls --all

  $ sl alias ls --format json

`sl alias options`

Get available options for creating aliases

USAGE
  $ sl alias options [--config <value>] [--format plain|json|yaml] [--hostname <value>] [--domain <value>]
    [--custom] [--premium] [--prefix]

FLAGS
  --config=<value>    [env: SIMPLELOGIN_CONFIG] Path to config file containing credentials
  --custom            Filter options for custom ones
  --domain=<value>    Filter options for specific mail domain
  --format=<option>   [default: plain] Output format
                      <options: plain|json|yaml>
  --hostname=<value>  Get options for specific hostname
  --prefix            Filter options for those that have a prefix in front of their suffix before the @
  --premium           Filter options for premium ones

DESCRIPTION
  Get available options for creating aliases

EXAMPLES
  $ sl alias options

  $ sl alias options --hostname example.com

  $ sl alias options --domain mydomain.com

  $ sl alias options --custom

  $ sl alias options --premium

  $ sl alias options --prefix

  $ sl alias options --custom --domain mydomain.com

  $ sl alias options --format json

See code: src/commands/alias/options.ts

`sl alias rm ALIAS-ID`

Delete an alias by ID

USAGE
  $ sl alias rm ALIAS-ID [--config <value>] [--format plain|json|yaml] [--confirm]

ARGUMENTS
  ALIAS-ID  Alias ID to delete

FLAGS
  --config=<value>   [env: SIMPLELOGIN_CONFIG] Path to config file containing credentials
  --confirm          Skip confirmation prompt
  --format=<option>  [default: plain] Output format
                     <options: plain|json|yaml>

DESCRIPTION
  Delete an alias by ID

ALIASES
  $ sl alias rm

EXAMPLES
  $ sl alias rm 123

  $ sl alias rm 123 --confirm

  $ sl alias rm 123 --format json

  $ sl alias rm 123 --confirm

`sl alias search QUERY`

Search aliases by email address

USAGE
  $ sl alias search QUERY [--config <value>] [--format plain|json|yaml] [--page <value>] [--pinned | --disabled |
    --enabled] [--all]

ARGUMENTS
  QUERY  Search query for alias email

FLAGS
  --all              Fetch all pages automatically
  --config=<value>   [env: SIMPLELOGIN_CONFIG] Path to config file containing credentials
  --disabled         Show only disabled aliases
  --enabled          Show only enabled aliases
  --format=<option>  [default: plain] Output format
                     <options: plain|json|yaml>
  --page=<value>     Page number (20 aliases per page)
  --pinned           Show only pinned aliases

DESCRIPTION
  Search aliases by email address

EXAMPLES
  $ sl alias search myalias

  $ sl alias search "john@" --page 1

  $ sl alias search example --pinned

  $ sl alias search test --all

  $ sl alias search search --format json

See code: src/commands/alias/search.ts

`sl alias update ALIAS-ID`

Update alias settings

USAGE
  $ sl alias update ALIAS-ID [--config <value>] [--format plain|json|yaml] [--note <value>] [--name <value>]
    [--mailbox-id <value>] [--mailbox-ids <value>] [--pinned] [--disable-pgp]

ARGUMENTS
  ALIAS-ID  Alias ID

FLAGS
  --config=<value>       [env: SIMPLELOGIN_CONFIG] Path to config file containing credentials
  --disable-pgp          Disable/enable PGP
  --format=<option>      [default: plain] Output format
                         <options: plain|json|yaml>
  --mailbox-id=<value>   Change primary mailbox
  --mailbox-ids=<value>  Comma-separated mailbox IDs
  --name=<value>         Update display name
  --note=<value>         Update note
  --pinned               Pin/unpin alias

DESCRIPTION
  Update alias settings

EXAMPLES
  $ sl alias update 123 --note "Updated note"

  $ sl alias update 123 --name "My Alias"

  $ sl alias update 123 --mailbox-id 456

  $ sl alias update 123 --mailbox-ids "456,789"

  $ sl alias update 123 --pinned

  $ sl alias update 123 --disable-pgp

  $ sl alias update 123 --note "Shopping" --pinned --format json

See code: src/commands/alias/update.ts

`sl config`

Display current configuration

USAGE
  $ sl config [--config <value>] [--format plain|json|yaml] [--show-key]

FLAGS
  --config=<value>   [env: SIMPLELOGIN_CONFIG] Path to config file containing credentials
  --format=<option>  [default: plain] Output format
                     <options: plain|json|yaml>
  --show-key         Show full API key (default: redacted)

DESCRIPTION
  Display current configuration

EXAMPLES
  $ sl config

  $ sl config --show-key

  $ sl config --format json

See code: src/commands/config.ts

`sl help [COMMAND]`

Display help for sl.

USAGE
  $ sl help [COMMAND...] [-n]

ARGUMENTS
  [COMMAND...]  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for sl.

See code: @oclif/plugin-help

`sl login`

Authenticate with SimpleLogin and store credentials

USAGE
  $ sl login [--config <value>] [--format plain|json|yaml] [--device <value>] [--key <value>] [--url
    <value>]

FLAGS
  --config=<value>   [env: SIMPLELOGIN_CONFIG] Path to config file containing credentials
  --device=<value>   [default: simplelogin-cli] Device name for the API key
  --format=<option>  [default: plain] Output format
                     <options: plain|json|yaml>
  --key=<value>      API key (prefer interactive prompt for security)
  --url=<value>      SimpleLogin instance URL (e.g., https://app.simplelogin.io)

DESCRIPTION
  Authenticate with SimpleLogin and store credentials

EXAMPLES
  $ sl login

  $ sl login --url https://app.simplelogin.io

  $ sl login --key api-key

See code: src/commands/login.ts

`sl logout`

Remove API credentials from config

USAGE
  $ sl logout [--config <value>] [--format plain|json|yaml]

FLAGS
  --config=<value>   [env: SIMPLELOGIN_CONFIG] Path to config file containing credentials
  --format=<option>  [default: plain] Output format
                     <options: plain|json|yaml>

DESCRIPTION
  Remove API credentials from config

EXAMPLES
  $ sl logout

  $ sl logout --format json

See code: src/commands/logout.ts

`sl whoami`

Check the authenticated user

USAGE
  $ sl whoami [--config <value>] [--format plain|json|yaml]

FLAGS
  --config=<value>   [env: SIMPLELOGIN_CONFIG] Path to config file containing credentials
  --format=<option>  [default: plain] Output format
                     <options: plain|json|yaml>

DESCRIPTION
  Check the authenticated user

EXAMPLES
  $ sl whoami

  $ sl whoami --format json

See code: src/commands/whoami.ts

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Installation

Usage

Automation & Scripting

Why This Matters

Output Format Control

Practical Automation Examples

Extract All Alias Emails

Automated Alias Generation Script

Filter and Export Specific Aliases

Password Manager Integration

Integration Benefits

Commands

sl alias create

sl alias create-custom PREFIX SUFFIX

sl alias custom PREFIX SUFFIX

sl alias delete ALIAS-ID

sl alias list

sl alias ls

sl alias options

sl alias rm ALIAS-ID

sl alias search QUERY

sl alias update ALIAS-ID

sl config

sl help [COMMAND]

sl login

sl logout

sl whoami