CLI Commands¶

Titlani provides the titlani command-line tool for sending messages, running servers, and managing identities.

`init`¶

Interactive wizard to generate server and client config files.

titlani init [OPTIONS]

Options:

Option	Short	Default	Description
`--output-dir`	`-o`	`~/.config/titlani`	Directory to write config files to
`--force`	`-f`	`false`	Overwrite existing config files

The wizard walks through three steps:

Essentials — hostname, port, mailbox directory
Feature toggles — GMAP, sender verification, encryption, auto-reply, rate limiting, access control
Feature details — follow-up prompts for each enabled feature

Output files:

server.toml — Server configuration
config.toml — Client configuration (references server.toml)

Example:

titlani init
titlani init --output-dir ./config --force

`send`¶

Send a Misfin message.

titlani send <to> <message> [OPTIONS]

Arguments:

Argument	Description
`to`	Recipient address (`mailbox@hostname`)
`message`	Message body text

Options:

Option	Short	Default	Description
`--subject`	`-s`	—	Message subject (prepended as `#` heading)
`--cert`	—	—	Path to sender identity certificate
`--key`	—	—	Path to sender identity private key
`--timeout`	`-t`	`30.0`	Request timeout in seconds

Example:

titlani send bob@example.com "Hello, Bob!" \
    --cert alice.pem --key alice.key \
    --subject "Greetings"

`serve`¶

Start a Misfin server.

titlani serve [OPTIONS]

Options:

Option	Short	Default	Description
`--config`	`-c`	—	Path to TOML config file
`--host`	`-h`	`localhost`	Server bind address
`--port`	`-p`	`1958`	Server port
`--hostname`	—	`localhost`	Hostname for mail routing
`--cert`	—	—	Path to TLS certificate
`--key`	—	—	Path to TLS private key
`--mailbox-dir`	—	`mailboxes`	Directory for mailbox storage
`--gmap-port`	—	—	GMAP server port (overrides config)
`--log-level`	`-l`	`INFO`	Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`)

CLI options override values from the config file.

Example:

titlani serve --config server.toml --log-level DEBUG

`identity generate`¶

Generate a Misfin identity certificate.

titlani identity generate <mailbox> <hostname> [OPTIONS]

Arguments:

Argument	Description
`mailbox`	Mailbox name (e.g., `alice`)
`hostname`	Hostname (e.g., `example.com`)

Options:

Option	Short	Default	Description
`--blurb`	`-b`	`""`	Human-readable description
`--output-dir`	`-o`	`.`	Output directory
`--valid-days`	—	`365`	Certificate validity in days
`--key-size`	—	`2048`	RSA key size in bits
`--with-encryption-key`	—	`false`	Also generate X25519 keypair for at-rest encryption
`--install`	—	`false`	Copy `.pem` to server's identity cert directory for GMAP auth
`--config`	—	`~/.config/titlani/server.toml`	Server config path (used with `--install`)

Output files:

<mailbox>.pem — Certificate file
<mailbox>.key — Private key file (mode 600)
<mailbox>.enc.pub — Encryption public key (only with --with-encryption-key)
<mailbox>.enc.key — Encryption private key, mode 600 (only with --with-encryption-key)

When --install is used, the .pem is also copied to the server's identity cert directory (from identity_cert_dir in server config, or mailbox_dir as fallback) and the mailbox subdirectory is created.

Examples:

titlani identity generate alice example.com \
    --blurb "Alice Smith" --output-dir ./certs \
    --with-encryption-key

# Generate and install for GMAP authentication
titlani identity generate alice example.com \
    --blurb "Alice Smith" --install

# With custom server config
titlani identity generate alice example.com \
    --install --config /etc/titlani/server.toml

`identity info`¶

Display identity information from a certificate file.

titlani identity info <cert_file>

Arguments:

Argument	Description
`cert_file`	Path to certificate file

Output fields: Address, Blurb, Hostname, Fingerprint, Not Before, Not After.

`tofu list`¶

List all hosts in the TOFU database.

titlani tofu list

Output columns: Hostname, Port, Fingerprint, First Seen, Last Seen.

`tofu revoke`¶

Remove a host from the TOFU database.

titlani tofu revoke <hostname> [OPTIONS]

Arguments:

Argument	Description
`hostname`	Hostname to revoke

Options:

Option	Short	Default	Description
`--port`	`-p`	`1958`	Port number

`mail list`¶

List messages in a mailbox directory.

titlani mail list [mailbox_dir]

Arguments:

Argument	Description
`mailbox_dir`	Path to mailbox directory (optional — auto-detected from client config if omitted)

The mailbox name is always derived from the current OS user ($USER).

Messages are listed newest-first with a # index column. You can pass the index number to mail read to open a message directly.

Unread messages (.gemmail.new) are shown with a NEW indicator. The table title includes a count of new messages (e.g., "Messages (5) (2 new)").

Encrypted messages (.gemmail.enc) are shown with an encrypted indicator.

Examples:

# Auto-detect mailbox directory from config, mailbox from $USER
titlani mail list

# Explicit directory
titlani mail list /var/mail/misfin

`mail search`¶

Search messages by sender, subject, or body text.

titlani mail search [query] [OPTIONS]

Arguments:

Argument	Description
`query`	Text to search for across all fields (optional if filters are provided)

Options:

Option	Short	Default	Description
`--from`	`-f`	—	Filter by sender address or name
`--subject`	`-s`	—	Filter by subject text
`--body`	`-b`	—	Filter by body text
`--mailbox-dir`	`-d`	—	Mailbox directory (auto-detected from client config if omitted)
`--encryption-key`	`-e`	—	Path to X25519 private key for decrypting `.enc` messages

At least one of query, --from, --subject, or --body must be provided. When multiple filters are used, they are combined with AND logic — a message must match all filters.

Encrypted messages are skipped unless --encryption-key is provided.

Examples:

# Search across all fields
titlani mail search "meeting notes"

# Filter by sender
titlani mail search --from alice@example.com

# Combine filters (AND logic)
titlani mail search --from alice --subject "project" --body "deadline"

# Search encrypted messages too
titlani mail search "budget" --encryption-key ~/.titlani/alice.enc.key

`mail read`¶

Read and display a gemmail message. Accepts either a message index (from mail list) or a file path.

titlani mail read <message> [OPTIONS]

Arguments:

Argument	Description
`message`	Message index (from `mail list` output) or path to `.gemmail`/`.gemmail.enc` file

Options:

Option	Short	Default	Description
`--mailbox-dir`	`-d`	—	Mailbox directory for index resolution (auto-detected from client config if omitted)
`--encryption-key`	`-e`	—	Path to X25519 private key for decryption

When using an index, the mailbox directory is resolved from the explicit option, then client config. The mailbox name is derived from $USER.

Reading an unread message (.gemmail.new) automatically marks it as read by renaming it to .gemmail. This happens after the message is displayed.

For .gemmail.enc files, the CLI auto-discovers <mailbox>.enc.key from the mailbox parent directory. Use --encryption-key to override.

Examples:

# Read message #2 from the listing (uses config + $USER)
titlani mail read 2

# Read by index with explicit directory
titlani mail read 1 -d /var/mail/misfin

# Read by file path (still works)
titlani mail read mailboxes/alice/message.gemmail.enc \
    --encryption-key ~/.titlani/alice.enc.key

`mail reply`¶

Reply to a gemmail message.

titlani mail reply <gemmail_file> [OPTIONS]

Arguments:

Argument	Description
`gemmail_file`	Path to `.gemmail` or `.gemmail.enc` file to reply to

Options:

Option	Short	Default	Description
`--message`	`-m`	—	Reply message body (opens `$EDITOR` if omitted)
`--quote`	`-q`	`false`	Quote original message with `>` prefix
`--cert`	—	—	Path to sender identity certificate
`--key`	—	—	Path to sender identity private key
`--encryption-key`	`-e`	—	Path to X25519 private key for decryption
`--timeout`	`-t`	`30.0`	Request timeout in seconds

Example:

titlani mail reply mailboxes/alice/message.gemmail.enc \
    --encryption-key ~/.titlani/alice.enc.key \
    --cert alice.pem --key alice.key \
    --message "Thanks for your message!"

`mail block`¶

Block a sender address from delivering mail to a mailbox.

titlani mail block <address> [OPTIONS]

Arguments:

Argument	Description
`address`	Sender address to block (`mailbox@hostname`)

Options:

Option	Short	Default	Description
`--mailbox-dir`	`-d`	—	Mailbox directory (auto-detected from client config if omitted)

The mailbox name is derived from $USER.

Example:

titlani mail block spam@evil.com
titlani mail block spam@evil.com -d /var/mail/misfin

See Contact Blocking for details.

`mail unblock`¶

Remove a sender address from the block list.

titlani mail unblock <address> [OPTIONS]

Arguments:

Argument	Description
`address`	Sender address to unblock

Options:

Option	Short	Default	Description
`--mailbox-dir`	`-d`	—	Mailbox directory (auto-detected from client config if omitted)

The mailbox name is derived from $USER.

Example:

titlani mail unblock spam@evil.com

`mail delete`¶

Delete one or more stored messages.

titlani mail delete <messages...> [OPTIONS]

Arguments:

Argument	Description
`messages`	Message indices (from `mail list`) or paths to `.gemmail`/`.gemmail.enc` files

Options:

Option	Short	Default	Description
`--mailbox-dir`	`-d`	—	Mailbox directory for index resolution (auto-detected from client config if omitted)
`--force`	`-f`	`false`	Skip confirmation prompt

Examples:

# Delete by index
titlani mail delete 3

# Delete multiple messages by index
titlani mail delete 1 2 5

# Delete by file path
titlani mail delete mailboxes/alice/message.gemmail

# Skip confirmation
titlani mail delete 1 2 --force

`admin fixperms`¶

Fix permissions on mailbox directories. Sets each mailbox subdirectory to mode 0700 and warns about ownership mismatches.

titlani admin fixperms [OPTIONS]

Options:

Option	Short	Default	Description
`--mailbox-dir`	`-d`	—	Mailbox directory (auto-detected if omitted)
`--dry-run`	—	`false`	Show what would be changed without making changes

Examples:

# Audit permissions (dry run)
titlani admin fixperms --dry-run

# Fix permissions
titlani admin fixperms

# Explicit directory
titlani admin fixperms -d /var/mail/misfin

`list create`¶

Create a new mailing list mailbox.

titlani list create <listname> [OPTIONS]

Arguments:

Argument	Description
`listname`	Mailing list name (alphanumeric, dots, dashes, underscores)

Options:

Option	Short	Default	Description
`--mailbox-dir`	`-d`	—	Mailbox directory

Example:

titlani list create dev-announce

`list subscribers`¶

Show subscribers for a mailing list. Displays confirmed and pending subscribers with status tags.

titlani list subscribers <listname> [OPTIONS]

Arguments:

Argument	Description
`listname`	Mailing list name

Options:

Option	Short	Default	Description
`--mailbox-dir`	`-d`	—	Mailbox directory

Example output:

dev-announce subscribers (3):
  alice@example.com [confirmed]
  bob@remote.host [confirmed]
  carol@another.host [pending]

`list add`¶

Add a subscriber to a mailing list. By default, sends a verification token that must be confirmed before the subscription is active.

titlani list add <listname> <address> [OPTIONS]

Arguments:

Argument	Description
`listname`	Mailing list name
`address`	Subscriber address (`mailbox@hostname`)

Options:

Option	Short	Default	Description
`--mailbox-dir`	`-d`	—	Mailbox directory
`--hostname`	`-H`	—	Server hostname for sending confirmation (reads from server config if not provided)
`--no-verify`	—	`false`	Skip verification and add directly

Examples:

# Add with verification (sends confirmation token)
titlani list add dev-announce alice@example.com -H mail.example.com

# Add directly without verification
titlani list add dev-announce alice@example.com --no-verify

`list remove`¶

Remove a subscriber from a mailing list. Also removes any pending verification entry.

titlani list remove <listname> <address> [OPTIONS]

Arguments:

Argument	Description
`listname`	Mailing list name
`address`	Subscriber address to remove

Options:

Option	Short	Default	Description
`--mailbox-dir`	`-d`	—	Mailbox directory

Example:

titlani list remove dev-announce alice@example.com

`verification list`¶

List all verified senders.

titlani verification list [OPTIONS]

Options:

Option	Short	Default	Description
`--cache`	`-c`	—	Path to verification cache database

`verification spki list`¶

List all cached server SPKI hashes.

titlani verification spki list [OPTIONS]

Options:

Option	Short	Default	Description
`--cache`	`-c`	—	Path to verification cache database

`verification spki clear`¶

Clear all cached server SPKI hashes.

titlani verification spki clear [OPTIONS]

Options:

Option	Short	Default	Description
`--cache`	`-c`	—	Path to verification cache database
`--force`	`-f`	`false`	Skip confirmation prompt

`version`¶

Display version information.

titlani version

CLI Commands¶

init¶

send¶

serve¶

identity generate¶

identity info¶

tofu list¶

tofu revoke¶

mail list¶

mail search¶

mail read¶

mail reply¶

mail block¶

mail unblock¶

mail delete¶

admin fixperms¶

list create¶

list subscribers¶

list add¶

list remove¶

verification list¶

verification spki list¶

verification spki clear¶

version¶

`init`¶

`send`¶

`serve`¶

`identity generate`¶

`identity info`¶

`tofu list`¶

`tofu revoke`¶

`mail list`¶

`mail search`¶

`mail read`¶

`mail reply`¶

`mail block`¶

`mail unblock`¶

`mail delete`¶

`admin fixperms`¶

`list create`¶

`list subscribers`¶

`list add`¶

`list remove`¶

`verification list`¶

`verification spki list`¶

`verification spki clear`¶

`version`¶