three-blocks-login

Minimal, dependency-free CLI for authenticating to Three Blocks private npm registry (AWS CodeArtifact).

Quick Start

# Interactive login (writes to .npmrc in current directory)
npx -y three-blocks-login@latest

# Using pnpm (recommended - no warnings)
npx -y three-blocks-login@latest@latest

Authentication Modes

The CLI supports three modes for storing authentication:

1. Project Mode (Default)

Writes .npmrc to the current directory. Best for project-specific authentication.

npx -y three-blocks-login@latest --mode project --scope @three-blocks --channel stable

For CI/CD: Run this command BEFORE pnpm install, not as a preinstall hook. See CI/CD Setup for platform-specific examples.

Note: Flags are optional - the CLI auto-detects --mode project in CI environments, defaults to --scope @three-blocks, and --channel stable.

2. Env Mode (Temporary)

Writes to a temporary .npmrc file and exports NPM_CONFIG_USERCONFIG. Useful for shell sessions.

eval "$(npx -y three-blocks-login@latest --mode env --print-shell)"

3. User Mode (Global)

Updates your user's npm config (~/.npmrc). Affects all projects.

npx -y three-blocks-login@latest --mode user

CLI Options

| Option | Description | Default | |--------|-------------|---------| | --mode <env\|project\|user> | Authentication storage mode | Auto-detected | | --scope <scope> | npm scope to authenticate | @three-blocks | | --channel <stable\|alpha\|beta> | Release channel | stable or THREE_BLOCKS_CHANNEL env | | --license <key> | License key (or use THREE_BLOCKS_SECRET_KEY env) | From env or prompt | | --endpoint <url> | Custom broker endpoint | https://www.threejs-blocks.com/api/npm/token | | --quiet / -q | Suppress non-error output | false | | --verbose / -v | Enable verbose logging | false | | --debug | Enable debug logging | false | | --non-interactive | Fail instead of prompting | false or CI=1 | | --print-shell | Print shell export commands (env mode) | false or THREE_BLOCKS_LOGIN_PRINT_SHELL=1 |

Environment Variables

| Variable | Description | |----------|-------------| | THREE_BLOCKS_SECRET_KEY | License key (format: tb_...) | | THREE_BLOCKS_CHANNEL | Release channel (stable, alpha, beta) | | THREE_BLOCKS_BROKER_URL | Custom broker endpoint URL | | THREE_BLOCKS_DEBUG | Enable debug logging (1, true, yes) | | THREE_BLOCKS_USER_NAME | Display name for welcome message | | THREE_BLOCKS_LOGIN_PRINT_SHELL | Print shell exports in env mode (1) | | CI | Enable non-interactive mode (1) |

CI/CD Setup

⚠️ pnpm users: The preinstall hook approach is unreliable with pnpm because pnpm resolves packages BEFORE running preinstall scripts. Use the CI Install Override approach below instead.

Recommended: CI Install Override (All CIs)

Run the login command BEFORE pnpm install, not as a preinstall hook:

Vercel

// vercel.json
{
  "installCommand": "npx -y three-blocks-login@latest && pnpm install"
}

Set THREE_BLOCKS_SECRET_KEY in Vercel → Project Settings → Environment Variables.

AWS Amplify

# amplify.yml
version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npx -y three-blocks-login@latest
        - pnpm install
    build:
      commands:
        - pnpm build

Set THREE_BLOCKS_SECRET_KEY in Amplify Console → App Settings → Environment Variables.

GitHub Actions

- name: Auth three-blocks
  run: npx -y three-blocks-login@latest
  env:
    THREE_BLOCKS_SECRET_KEY: ${{ secrets.THREE_BLOCKS_SECRET_KEY }}

- name: Install dependencies
  run: pnpm install

Netlify

# netlify.toml
[build]
  command = "npx -y three-blocks-login@latest && pnpm install && pnpm build"

Set THREE_BLOCKS_SECRET_KEY in Netlify → Site Settings → Environment Variables.

Generic CI

Always run login before install:

npx -y three-blocks-login@latest && pnpm install

Alternative: Preinstall Hook (npm only)

⚠️ This approach only works reliably with npm, not pnpm. For pnpm, use CI Install Override above.

1. Commit a base .npmrc (no auth token):

   @three-blocks:registry=https://three-blocks-196905988268.d.codeartifact.ap-northeast-1.amazonaws.com/npm/core/

2. Add preinstall script:

   {
     "scripts": {
       "preinstall": "npx -y three-blocks-login@latest"
     }
   }

3. Set THREE_BLOCKS_SECRET_KEY in CI environment variables.

Troubleshooting

401 Unauthorized on Vercel/Amplify/CI

Problem: Getting ERR_PNPM_FETCH_401 or 401 errors in CI.

Root Cause: pnpm resolves packages BEFORE running preinstall scripts. If you're using a preinstall hook with pnpm, it won't work reliably.

Solution: Use CI Install Override instead of preinstall hooks.

For Vercel, add to vercel.json:

{
  "installCommand": "npx -y three-blocks-login@latest && pnpm install"
}

For other CIs, see the CI/CD Setup section above.

Also check:

• THREE_BLOCKS_SECRET_KEY is set in CI environment variables
• .npmrc does NOT contain an _authToken line (tokens expire in 12h)
• Remove any preinstall hook from package.json if using CI override

License Key Format

License keys must:

• Start with tb_ prefix
• Contain at least 10 characters after the prefix
• Only contain characters: A-Z, a-z, 0-9, _, -

Example: tb_AbC123XyZ456...

Token Expiry

Tokens are short-lived (typically 12 hours). If you see 401 errors:

1. Check that THREE_BLOCKS_SECRET_KEY is set correctly
2. Run the preinstall script manually to test: npm run preinstall or pnpm preinstall
3. Verify the broker endpoint is accessible: curl -I https://www.threejs-blocks.com/api/npm/token

npm Config Warnings

If you see warnings like npm WARN invalid config unknown="...":

• Use pnpm dlx instead of npx
• Or ignore the warnings (they're harmless)

Security

• License keys are validated locally before being sent to the broker
• Tokens are masked in CLI output (••••{last4})
• .npmrc files are created with 0o600 permissions (read/write for owner only)
• Sensitive environment variables are scrubbed before running npm commands

What's Safe to Commit?

✅ SAFE - Base .npmrc with registry URL only:

@three-blocks:registry=https://three-blocks-196905988268.d.codeartifact.ap-northeast-1.amazonaws.com/npm/core/

❌ NEVER COMMIT - Lines containing auth tokens:

//three-blocks-196905988268.d.codeartifact.ap-northeast-1.amazonaws.com/npm/core/:_authToken=eyJ2...

❌ NEVER COMMIT - .env.local with license keys

Add to your .gitignore:

.env.local

Note: You can now commit .npmrc safely - the preinstall script merges auth tokens without overwriting your base configuration.

How It Works

1. License Key Validation: The CLI validates your license key format locally
2. Broker Request: Sends your license key to the broker endpoint via Bearer auth
3. Token Exchange: The broker returns a short-lived npm token and registry URL
4. npm Configuration: Writes authentication to .npmrc in the selected mode

License Key → Broker Service → Short-lived NPM Token → CodeArtifact Access

License Tiers

The CLI supports multiple license tiers:

• Indie/Core: Access to @three-blocks/core package
• Pro: Access to all @three-blocks/* packages including starter templates

Your tier is determined by your license key and displayed in the CLI output.

Support

For issues or questions:

• Check the troubleshooting guide above
• Review your Vercel environment variables
• Verify your license key format
• Contact Three Blocks support with your license ID (not the full key)

Version

Current version: 0.1.4

For the latest version, always use @latest:

npx -y three-blocks-login@latest