Authentication

nmbl requires authentication to use. You can authenticate using either OAuth or a license key.

OAuth Authentication (Recommended)#

OAuth provides secure authentication through your Google account.

Sign In#

nmbl login

This command:

1. Opens a browser window
2. Redirects to Google authentication
3. Validates your email domain
4. Stores authentication token securely

Authorized Domains:

• @nimblepros.com
• Other configured domains

Check Authentication Status#

nmbl whoami

Shows:

• Authentication method (OAuth or License Key)
• User email (for OAuth)
• Token expiration
• License status

Sign Out#

nmbl logout

Removes all stored authentication tokens.

License Key Authentication#

If you have a license key, you can use it instead of OAuth.

Configuration Priority#

nmbl checks for license keys in this order:

1. Command line argument (highest priority)
2. Environment variable
3. User configuration file
4. Local appsettings.json (lowest priority)

Method 1: Command Line Argument#

Pass the license key with each command:

nmbl --license-key YOUR_LICENSE_KEY cc MyProject.csproj
nmbl -l YOUR_LICENSE_KEY deps MySolution.slnx

Pros:

• No configuration needed
• Easy to use in CI/CD

Cons:

• Must be specified every time
• Visible in command history

Method 2: Environment Variable#

Set the NMBL_LICENSE_KEY environment variable:

Windows PowerShell:

# Current session only
$env:NMBL_LICENSE_KEY = "YOUR_LICENSE_KEY"

# Permanently (user level)
[System.Environment]::SetEnvironmentVariable('NMBL_LICENSE_KEY', 'YOUR_LICENSE_KEY', 'User')

# Permanently (system level - requires admin)
[System.Environment]::SetEnvironmentVariable('NMBL_LICENSE_KEY', 'YOUR_LICENSE_KEY', 'Machine')

Windows Command Prompt:

# Current session only
set NMBL_LICENSE_KEY=YOUR_LICENSE_KEY

# Permanently (user level)
setx NMBL_LICENSE_KEY "YOUR_LICENSE_KEY"

Linux/macOS (Bash/Zsh):

# Current session only
export NMBL_LICENSE_KEY="YOUR_LICENSE_KEY"

# Permanently (add to ~/.bashrc or ~/.zshrc)
echo 'export NMBL_LICENSE_KEY="YOUR_LICENSE_KEY"' >> ~/.bashrc
source ~/.bashrc

Pros:

• No need to specify with each command
• Works well in CI/CD environments

Cons:

• Requires shell/system configuration
• May expose key in environment

Method 3: User Configuration File#

Create a configuration file at:

Windows:

%APPDATA%\nmbl\config.json

Linux/macOS:

~/.config/nmbl/config.json

File contents:

{
  "licenseKey": "YOUR_LICENSE_KEY"
}

Create the file (Windows PowerShell):

$configPath = "$env:APPDATA\nmbl"
New-Item -ItemType Directory -Force -Path $configPath
Set-Content -Path "$configPath\config.json" -Value '{"licenseKey": "YOUR_LICENSE_KEY"}'

Create the file (Linux/macOS):

mkdir -p ~/.config/nmbl
echo '{"licenseKey": "YOUR_LICENSE_KEY"}' > ~/.config/nmbl/config.json

Pros:

• Persistent across sessions
• Not visible in command history
• User-specific configuration

Cons:

• Requires file creation
• One configuration per user

Method 4: Local appsettings.json#

Place an appsettings.json file in your current working directory:

{
  "licenseKey": "YOUR_LICENSE_KEY"
}

Pros:

• Project-specific configuration
• Easy to share with team (if appropriate)

Cons:

• Different configuration per directory
• Risk of committing to source control

Important: Add to .gitignore:

appsettings.json

Security Best Practices#

Protecting Your License Key#

1. Never commit license keys to source control

   # .gitignore
   appsettings.json
   config.json

2. Use environment variables in CI/CD

   • GitHub Actions: Use secrets
   • Azure DevOps: Use pipeline variables
   • GitLab CI: Use protected variables

3. Limit key exposure

   • Prefer OAuth when possible
   • Use user config file over environment variables
   • Rotate keys periodically

Token Storage#

OAuth tokens are stored securely:

• Windows: Encrypted using DPAPI in %APPDATA%\nmbl\tokens.json
• Linux/macOS: Protected file at ~/.config/nmbl/tokens.json (0600 permissions)

Troubleshooting#

“Authentication required” error#

Try these steps:

1. Check authentication status:

   nmbl whoami

2. For OAuth users:

   nmbl logout
   nmbl login

3. For license key users:

   • Verify key is correctly set
   • Check configuration priority
   • Ensure no typos in key

“Invalid license key” error#

• Verify the key is correct
• Check for extra spaces or quotes
• Contact support for key validation

OAuth browser not opening#

• Check firewall settings
• Verify browser is set as default
• Try manual URL from console output

Getting a License Key#

Contact NimblePros:

• Email: info@nimblepros.com
• Website: https://nimblepros.com

Next Steps#

• Getting Started - Install and configure nmbl
• Commands Reference - Learn available commands