Authentication

Authentication

The CLI uses device code flow for secure authentication. This opens your browser to complete login without exposing credentials in the terminal.

Login

transactional login

This will:

1. Display a verification code
2. Open your browser to the authorization page
3. Wait for you to approve the code
4. Store the authentication token securely

Login Options

Example

# Standard login
transactional login
 
# Force re-authentication
transactional login --force

Note: For MCP integration with Claude, authentication is handled automatically via OAuth 2.1. You don't need to run transactional login first - Claude will prompt you to authorize when you first use a Transactional tool. See MCP Setup for details.

Logout

Log out from all organizations:

transactional logout

This removes all stored credentials.

Who Am I

Check your current authentication status:

transactional whoami

Output includes:

• User ID and email
• Current organization (name, slug, role)
• Session information

Options

Organization Management

List Organizations

View all organizations you have access to:

transactional org list

The current organization is marked with *.

Select Organization

Set the active organization for CLI commands:

transactional org use <slug>

Quick Switch

Use the switch command as a shortcut:

transactional switch <slug>

Or without a slug to see an interactive picker:

transactional switch

Show Current Organization

transactional org current

Per-Command Organization Override

Any command can target a different organization using the -o flag:

# Send email from a specific organization
transactional email send \
  -o my-other-org \
  --from "hello@example.com" \
  --to "user@example.com" \
  --subject "Test" \
  --html "<p>Hello</p>"

Token Storage

Tokens are stored in ~/.transactional/credentials.json. This file is created with restricted permissions (readable only by you).

To view the credentials file location:

transactional config path

Session Types

Troubleshooting

"Not logged in" errors

Run transactional login to authenticate.

"Organization not found"

1. Check available organizations: transactional org list
2. Verify the slug spelling
3. Ensure you have been invited to the organization

Token expired

Run transactional login --force to get a new token.