CLI Reference

Installation

pip install oneshot-mail

The oneshot command is included with the Python SDK. It wraps the SDK with a rich terminal UI using Click and Rich.

Configuration

API key

Set your API key using any of these methods (in priority order):

# 1. Environment variable (highest priority)
export ONESHOT_API_KEY="osm_live_your_key"

# 2. Config command
oneshot config set api-key osm_live_your_key

The config file is stored at ~/.config/oneshot/config.toml.

Verify your setup

oneshot whoami

This prints your account details, plan, and usage.

---

Commands

oneshot create

Create a new receive-mode email address and optionally wait for an email to arrive.

# Create and print the address
oneshot create

# Create with custom TTL and label
oneshot create --ttl 30m --label "ci-test"

# Create and wait for an email (interactive, shows a live spinner)
oneshot create --wait

# Create and wait with a custom timeout
oneshot create --wait --timeout 120

# Output as JSON (for scripting)
oneshot create --ttl 5m --label "ci-test" --json

Flags:

Flag	Type	Default	Description
--ttl	string	1h	Time-to-live (e.g., 30s, 5m, 1h).
--label	string	(none)	Label for filtering and cleanup.
--wait	flag	false	Wait for an email to arrive before exiting.
--timeout	int	60	Seconds to wait (with --wait).
--json	flag	false	Output raw JSON.

When --wait is used, the CLI shows a live spinner with elapsed time, then renders the email beautifully when it arrives (sender, subject, text preview in a rich panel).

---

oneshot send

Send a one-shot email from a temporary address.

# Simple text email
oneshot send --to intake@myapp.com --subject "Test" --body "Hello world"

# HTML email from a file
oneshot send --to intake@myapp.com --subject "Test" --html-file ./email.html

# With attachments
oneshot send --to intake@myapp.com --subject "Invoice" --body "See attached" --attach invoice.pdf

# Multiple attachments
oneshot send --to intake@myapp.com --subject "Report" --body "See attached" \
  --attach report.pdf --attach data.csv

# JSON output for scripting
oneshot send --to intake@myapp.com --subject "Test" --body "Hi" --json

Flags:

Flag	Type	Description
--to	string	Destination email address (required).
--subject	string	Email subject (required).
--body	string	Plain text body.
--html-file	path	Path to an HTML file for the body.
--attach	path	Attachment file path (repeatable).
--ttl	string	TTL for the address record.
--label	string	Optional label.
--json	flag	Output raw JSON.

---

oneshot get

Retrieve and display an email for a given address ID.

# Show email summary (from, subject, snippet)
oneshot get abc123xyz789def456

# Show full email body
oneshot get abc123xyz789def456 --full

# Open HTML body in browser
oneshot get abc123xyz789def456 --html

# View raw RFC 822 source
oneshot get abc123xyz789def456 --raw

# Save raw email to file
oneshot get abc123xyz789def456 --save ./email.eml

# Download all attachments to a directory
oneshot get abc123xyz789def456 --save-attachments ./attachments/

# JSON output
oneshot get abc123xyz789def456 --json

Flags:

Flag	Type	Description
--full	flag	Show complete email body.
--html	flag	Open HTML body in default browser.
--raw	flag	Show raw RFC 822 source.
--save	path	Save raw email to a file.
--save-attachments	path	Download all attachments to a directory.
--json	flag	Output raw JSON.

---

oneshot list

List your recent addresses in a rich table.

# List all addresses
oneshot list

# Filter by status
oneshot list --status waiting

# Filter by label (glob pattern)
oneshot list --label "ci-run-*"

# Filter by mode
oneshot list --mode send

# JSON output
oneshot list --json

Flags:

Flag	Type	Default	Description
--status	string	(all)	Filter: waiting, received, expired, sent.
--label	string	(all)	Filter by label (glob pattern).
--mode	string	(all)	Filter: receive or send.
--limit	int	20	Max results.
--json	flag	false	Output raw JSON.

The table uses colour-coded status indicators:

• Green: received
• Yellow: waiting
• Red: expired
• Blue: sent

---

oneshot delete

Delete addresses.

# Delete a single address
oneshot delete abc123xyz789def456

# Bulk delete by label
oneshot delete --label "ci-run-abc123"

Flags:

Flag	Type	Description
--label	string	Delete all addresses with this label.

---

oneshot whoami

Show your current account, plan, and usage.

oneshot whoami

Example output:

Account: developer@example.com
Plan:    Solo ($10/mo)

Usage this period:
  Receive: 142 / 10,000 (1%)
  Send:     23 / 1,000 (2%)

Credits remaining: 450
Billing cycle ends: 2026-04-07

---

oneshot credits buy

Purchase additional credits.

# Interactive -- select a pack
oneshot credits buy

# Direct -- specify amount
oneshot credits buy --amount 500

Opens a Stripe Checkout URL in your default browser.

---

oneshot ping

Check API health and measure latency.

oneshot ping

Example output:

API Status: ok
Region:     ap-southeast-2
Version:    1.2.3
Latency:    142ms

---

oneshot config set

Set configuration values.

oneshot config set api-key osm_live_your_key

oneshot login

Interactive login — opens a browser window where you can authenticate and the API key is automatically configured.

oneshot login

---

Global flags

These flags are available on all commands:

Flag	Description
--json	Output raw JSON (for scripting).
--version	Show CLI version.
--help	Show help for any command.

Environment variables

Variable	Description
ONESHOT_API_KEY	API key (takes precedence over config file).
ONESHOT_BASE_URL	Override the API base URL.
NO_COLOR	Disable all colour output when set.

Shell completions

The CLI supports shell completions for bash, zsh, and fish. Click generates these automatically:

# bash
eval "$(_ONESHOT_COMPLETE=bash_source oneshot)"

# zsh
eval "$(_ONESHOT_COMPLETE=zsh_source oneshot)"

# fish
_ONESHOT_COMPLETE=fish_source oneshot | source

Add the appropriate line to your shell profile (.bashrc, .zshrc, config.fish) for persistent completions.