Pilotiq
DocsGitHub

Install Pilotiq Pro

The Pilotiq Pro packages — @pilotiq-pro/ai and @pilotiq-pro/collab — are published to a private npm registry at npm.pilotiq.io. Access is gated by a per-customer install token that you generate from the portal once you have an active subscription.

Note

Don't have a license yet? See plans →

#1. Generate an install token

Sign in to the portal and open Tokens. Click Create token, give it a label that identifies the environment (local-dev, ci-staging, prod), and pick the install kind.

You'll see the raw token once — copy it immediately. Store it in your shell environment, your CI secret store, or your team's password manager. The portal only ever shows the prefix from then on.

Important

Tokens are not recoverable. If you close the page without copying, revoke the token and generate a new one — there's no display-again path by design.

#2. Configure .npmrc

Add the registry + auth-token directive to your project's .npmrc (or ~/.npmrc if you'd rather share one token across local projects):

.npmrc
@pilotiq-pro:registry=https://npm.pilotiq.io
//npm.pilotiq.io/:_authToken=${PILOTIQ_INSTALL_TOKEN}

Then export the token in your shell or .env:

terminal
export PILOTIQ_INSTALL_TOKEN=plq_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Tip

npm, pnpm, and yarn all expand ${VAR} references in .npmrc from the shell environment at install time. Keep the raw token out of any committed file.

#3. Install the Pro packages

terminal
pnpm add @pilotiq-pro/ai @pilotiq-pro/collab

Install only the packages you need — every Pro extension is independently versioned.

#4. Activate runtime (self-host only)

For self-hosted apps, Pilotiq Pro verifies your subscription on boot. Generate a separate token of kind runtime from the portal and expose it to your process:

terminal
export PILOTIQ_LICENSE_TOKEN=plq_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The Pro packages read PILOTIQ_LICENSE_TOKEN at boot, verify it against pilotiq.io/api/license/verify, cache the response for 60 seconds, and use it to gate features and meter credits per run.

Note

Hosted plans don't need a runtime token — verification happens on the infrastructure side. The install token is enough.

#Security

  • One token per environment. A separate local-dev, ci-staging, prod token means a leak from one is surgical to revoke without touching the others.
  • Install vs runtime kinds are distinct. Install tokens authenticate npm install against the registry; runtime tokens authenticate your running app against the license server. Don't reuse one as the other — revoking either won't affect the other if they're separate.
  • Rotate on schedule. A 90-day rotation cadence is the lowest-friction default. Add the date the token was created to its label so you remember.
  • The server stores hashes only. Pilotiq.io stores sha256(token) — the raw value is unrecoverable after creation, so a database breach can't leak working tokens.

#Troubleshooting

#401 Unauthorized on install

The registry rejected the token. Most common causes:

  1. Token wasn't expanded. Run echo $PILOTIQ_INSTALL_TOKEN — if it's empty, your shell didn't pick up the export. Source your .env or set the variable in your shell rc.
  2. Token revoked. Check the Tokens page — a revoked token shows a strikethrough and "Revoked" badge. Generate a new one.
  3. Wrong token kind. Install tokens authenticate the registry; runtime tokens won't work for npm install. Confirm the Kind column in the portal says "install".
  4. Subscription canceled. If your subscription is past its grace period, all tokens stop working. Check the portal dashboard for the current status.

#404 Not Found for @pilotiq-pro/

The .npmrc registry directive isn't being applied. Verify:

  • The .npmrc lives at the project root (or your home directory).
  • The scope line spells @pilotiq-pro exactly — note the hyphen, no underscore.
  • No other .npmrc higher up the directory tree is overriding it (check ~/.npmrc).

Run npm config get @pilotiq-pro:registry from the project directory to confirm the registry value npm sees.

#Scope conflict with existing .npmrc

If you already have an .npmrc configured for another private registry, append the Pro scope rather than replacing existing lines:

.npmrc
# Existing entries above…
@your-company:registry=https://npm.your-company.com

# Add Pilotiq Pro below.
@pilotiq-pro:registry=https://npm.pilotiq.io
//npm.pilotiq.io/:_authToken=${PILOTIQ_INSTALL_TOKEN}

Each scope is namespaced independently — they coexist.

#credits-exhausted at runtime

Your license has no remaining AI credits. Top up from the Credits page, or wait for the monthly allowance to reset. The reset date is shown on the portal dashboard.

#feature-not-licensed at runtime

The Pro package is trying to use a feature that's not included in your plan. The Pricing page lists what each plan includes; upgrade from the portal dashboard to unlock additional features.