three-blocks-login

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

Quick Start

``bash


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:

$3

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

`bash
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.

$3

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

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

$3

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

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

CLI Options

| Option | Description | Default |
|--------|-------------|---------|
| --mode | Authentication storage mode | Auto-detected |
| --scope | npm scope to authenticate | @three-blocks |
| --channel | Release channel | stable or THREE_BLOCKS_CHANNEL env |
| --license | License key (or use THREE_BLOCKS_SECRET_KEY env) | From env or prompt |
| --endpoint | 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.

$3

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

#### Vercel

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

Set THREE_BLOCKS_SECRET_KEY in Vercel → Project Settings → Environment Variables.

#### AWS Amplify

`yaml


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

`yaml
- 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

`toml


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:
`bash
npx -y three-blocks-login@latest && pnpm install
`

$3

> ⚠️ 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:
`json
{
"scripts": {
"preinstall": "npx -y three-blocks-login@latest"
}
}
`

3. Set THREE_BLOCKS_SECRET_KEY in CI environment variables.

Troubleshooting

$3

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:
`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

$3

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...

$3

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

$3

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

$3

✅ 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:
`bash
npx -y three-blocks-login@latest
``