Authentication
ntcli auth login
Authenticate with Clerk OAuth
Overview
Authenticate with the NimbleTools platform using Clerk OAuth. This command opens your browser to complete the OAuth flow and stores authentication credentials locally.Syntax
Options
Port for local callback server. Default:
41247Authentication timeout in milliseconds. Default:
60000 (60 seconds)Enable verbose output to show detailed authentication flow
Examples
Basic Authentication
- Start a local callback server on the default port (41247)
- Open your default browser to the NimbleTools OAuth page
- Wait for you to complete authentication
- Store the credentials locally for future use
Custom Port
Extended Timeout
Verbose Output
- Callback server startup
- OAuth URLs and parameters
- Token exchange details
Authentication Flow
1
Start Local Server
ntcli starts a local HTTP server to receive the OAuth callback
2
Open Browser
Your default browser opens to the NimbleTools OAuth page
3
Complete OAuth
Sign in with your existing account or create a new one
OAuth Provider Details
ntcli uses Clerk as the OAuth provider, supporting:- Email/Password authentication
- Social logins (Google, GitHub, etc.)
- Magic links for passwordless authentication
- Multi-factor authentication (MFA)
Credential Storage
Authentication credentials are stored securely:Stored in the macOS Keychain using the
keytar libraryTroubleshooting
Browser doesn't open automatically
Browser doesn't open automatically
Cause: System doesn’t have a default browser configured or browser launch failed.Solution: Copy the URL from the terminal output and open it manually in your browser.
Port already in use
Port already in use
Cause: The default port (41247) is being used by another application.Solution: Use a different port with
--port option:Timeout during authentication
Timeout during authentication
Cause: Authentication took longer than the timeout period.Solution: Increase timeout and try again:
Network connection issues
Network connection issues
Cause: Firewall or proxy blocking OAuth requests.Solution:
- Check firewall settings for the callback port
- Configure proxy settings if needed
- Use
--verboseto see detailed error messages
Environment Variables
The following environment variables affect authentication:| Variable | Description | Default |
|---|---|---|
CLERK_OAUTH_CLIENT_ID | OAuth client ID | Set automatically |
CLERK_DOMAIN | Clerk domain | Set automatically |
NTCLI_DEFAULT_PORT | Default callback port | 41247 |
Security Considerations
- Local callback server: Only runs during authentication and shuts down immediately after
- HTTPS enforcement: All OAuth flows use HTTPS for security
- Automatic cleanup: Failed authentication attempts clean up temporary servers
Related Commands
auth status
Check current authentication status and token validity
auth logout
Clear stored authentication credentials
workspace create
Create your first workspace after authentication
token refresh
Refresh workspace-specific access tokens
Next Steps
After successful authentication:- Check status:
ntcli auth status - Create workspace:
ntcli workspace create my-project - Browse servers:
ntcli registry list - Deploy server:
ntcli server deploy nationalparks-mcp