Skip to main content

​
Installation

Install the CLI tool globally using npm, or use npx to run it without installation: 
npm install -g username-dev
You can use npx username-dev without installing the package globally. This is convenient for one-off checks or when you don’t want to install packages globally.

​
Quick Start

Check a username using the check command: With global installation: 
username-dev check paris --api-key un_live_your_api_key_here
With npx (no installation required): 
npx username-dev check paris --api-key un_live_your_api_key_here
The command outputs JSON results: 
{
  "username": "paris",
  "isReserved": true,
  "isDeleted": false,
  "categories": [
    {
      "category": "city",
      "metadata": {
        "country": "FR"
      }
    }
  ]
}

​
Commands

​
check

Check if a username is reserved. Usage: 
username-dev check <username> [options]
Options:
  • --api-key, -k (required): Your API key
  • --output, -o: Output format (json or pretty, default: json)
Examples: 
# Check a username with JSON output
username-dev check berlin --api-key un_live_xxx

# Or with npx (no installation required)
npx username-dev check berlin --api-key un_live_xxx

# Check with pretty output
username-dev check admin --api-key un_live_xxx --output pretty

​
version

Display the CLI version. Usage: 
username-dev version

​
help

Display help information. Usage: 
username-dev help
username-dev help check

​
Configuration

​
Environment Variable

You can set your API key as an environment variable to avoid passing it on every command: Set for current session: 
export USERNAME_DEV_API_KEY=un_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
username-dev check test

# Works with npx too
npx username-dev check test
Set permanently (add to shell profile): For zsh (macOS default, newer Linux): 
echo 'export USERNAME_DEV_API_KEY=un_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' >> ~/.zshrc
source ~/.zshrc
For bash: 
echo 'export USERNAME_DEV_API_KEY=un_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' >> ~/.bashrc
source ~/.bashrc
The CLI will automatically use the USERNAME_DEV_API_KEY environment variable if the --api-key flag is not provided. This works with both global installation and npx.

​
Output Formats

​
JSON (default)

username-dev check paris --api-key un_live_xxx
Outputs raw JSON response.

​
Pretty

username-dev check paris --api-key un_live_xxx --output pretty
Outputs formatted, human-readable results.

​
Exit Codes

  • 0: Success
  • 1: Error (invalid input, API error, etc.)

​
Resources