CLI Authentication

Managing authentication and sessions for the msgs.global CLI

Overview

The msgs.global CLI uses token-based authentication to securely communicate with the management API. When you log in, a JWT (JSON Web Token) is issued and stored locally for subsequent commands.

Login

Authenticate with your msgs.global username and password:

msgsg> login
Username: alice
Password: ********
Authenticated as alice

You can also provide the username as an argument:

$ msgsg login alice
Password: ********
Authenticated as alice

The authentication token is stored in ~/.msgsg_token with secure permissions (0600).

Check Current User

View your currently authenticated user:

msgsg> whoami
{
  "username": "alice",
  "email": "alice@msgs.global",
  "role": "admin",
  "authenticated": true
}

Logout

Clear your local authentication token:

msgsg> logout
Session cleared.

This removes the ~/.msgsg_token file. You'll need to login again to use authenticated commands.

Token Security

Token Storage

Your authentication token is stored at:

~/.msgsg_token

Best Practices

  • Never share your token file with others
  • Use logout when finished with a session on shared systems
  • Tokens are created with restrictive permissions (readable only by you)
  • Tokens may expire after a period of inactivity - simply login again
  • For automation, consider using API keys instead of interactive login

API Keys for Automation

For scripts and automation where interactive password entry isn't feasible, you can generate API keys via the web interface or CLI: 

# Coming soon: API key management via CLI
msgsg apikey create --name "Backup Script" --expires 90d

# Use API key instead of interactive login
export MSGSG_API_KEY="your-api-key-here"
msgsg domain list
Note: API key support is currently available through the web interface only. CLI support is coming in a future release.

Troubleshooting

Authentication Failed

If login fails, verify:

  • Username and password are correct
  • Your account is active and not locked
  • Network connectivity to msgs.global API
  • 2FA code if two-factor authentication is enabled

Token Expired

If you see "unauthorized" or "token expired" errors, simply login again:

msgsg login

Permission Denied

Certain commands require specific roles (admin, super_admin). Verify your role:

msgsg whoami

Next Steps