Fetch a short-lived token from the three-blocks broker and configure npm for the current context.
npm install three-blocks-loginMinimal, dependency-free CLI for authenticating to Three Blocks private npm registry (AWS CodeArtifact).
``bashInteractive login (writes to .npmrc in current directory)
npx -y three-blocks-login@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 keysAdd 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 templatesYour 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
``