fledgling 🐣

Create and set up packages on npm with trusted publishing.

Brought to you by Varlock 🧙‍♂️🔐 — check it out to keep your secrets out of plaintext.

fledgling claims your package name on npm and sets up token-less (OIDC trusted) publishing — no NPM_TOKEN, no clicking through the npm website. It works for a single package or a whole monorepo, and it's idempotent, so you can re-run it any time you add a package.

Designed to be run with npx (or bunx / pnpm dlx):

npx fledgling                                # interactive walkthrough (in a terminal)
npx fledgling add my-great-new-idea --new    # claim a brand-new name, nothing in the repo yet
npx fledgling add "*" --yes                  # every package in a monorepo (globs ok)
npx fledgling sync                           # reconcile trusted publishing to your config

Run bare fledgling in a terminal and you get an interactive wizard (powered by clack); pass packages to add (or --yes / run in CI) and it goes non-interactive.

Commands

Command	What it does
fledgling	Interactive wizard (the default)
fledgling add [packages…]	Claim names + set up trusted publishing for the given packages
fledgling sync	Reconcile trusted publishing on npm with your config
fledgling init	Write the trusted-publishing config to your package.json

Why

Setting up a new npm package the modern way is more fiddly than it should be:

1. npm won't let you configure trusted publishing until the package already exists — so you have to publish something first.
2. Then you configure the trusted publisher per package, by hand, on the website.
3. In a monorepo, you do that N times.

fledgling does all of it: publishes a tiny placeholder to claim each name, then configures the trusted publisher for every package via npm's own npm trust. It's idempotent — re-run it whenever you add a package and it only does what's missing.

Quick start

npm login        # needs 2FA enabled
npx fledgling       # interactive: pick packages, confirm, apply

Prefer non-interactive (or in CI)?

npx fledgling --dry-run    # print a plan, change nothing
npx fledgling --yes        # apply: claim names + configure trusted publishing

Then add the matching publish step to your CI (e.g. a GitHub Actions job with permissions: id-token: write running npm publish). Your real releases now publish over OIDC — no token required.

🐸 Next step: Bumpy handles exactly that publish step for you — it versions your packages, writes changelogs, and publishes over OIDC trusted publishing (no NPM_TOKEN). fledgling sets up the trust, Bumpy does the releasing — they pair perfectly. (This repo is released with it.)

Configuration

The recommended way to configure fledgling is a "fledgling" block in your root package.json. Set it once and every run reads it — CLI flags are just per-run overrides. Create it interactively:

npx fledgling init

{
  "fledgling": {
    "provider": "github",       // github | gitlab | circleci
    "workflow": "release.yml",  // the workflow whose job runs `npm publish`
    "environment": "publish",   // CI environment for the trusted publisher (optional)
    "permissions": "publish"    // publish | stage | both
  }
}

CircleCI uses IDs instead of a workflow/repo:

{
  "fledgling": {
    "provider": "circleci",
    "orgId": "…",
    "projectId": "…",
    "pipelineDefinitionId": "…",
    "vcsOrigin": "github/owner/repo",
    "contextIds": ["…"],        // optional
    "permissions": "publish"
  }
}

Add "registry" to either block to target a non-default npm registry.

Excluding packages

fledgling skips any package marked "private": true. To exclude public packages too — internal-but-published things you never want it to claim or manage trust for — add an "ignore" list of names or globs:

{
  "fledgling": {
    "ignore": ["@scope/internal-*", "playground"]
  }
}

Ignored packages are invisible to fledgling: they're left out of add, sync, "*" globs, and tab completion.

Defaults

Option	Default	Notes
provider	github	also gitlab, circleci
repo	auto-detected from git origin	override with --repo
workflow	release.yml	the workflow whose job publishes
environment	none	Optional and unset by default — the trusted publisher then isn't tied to a CI environment (it works, but adds no environment gate). Setting one (e.g. publish) is recommended for security, and fledgling init pre-fills it.
permissions	publish	publish, stage (held for 2FA approval), or both
registry	your npm config	optional custom npm registry URL

CircleCI uses orgId, projectId, pipelineDefinitionId, vcsOrigin, and optional contextIds instead of repo/workflow/environment.

Precedence is CLI flag → fledgling config → built-in default.

Just want to claim names?

To skip trusted publishing entirely and only reserve package names, you can:

• pass --skip-trust for a single run,
• decline the wizard's "Set up trusted publishing?" prompt, or
• set "trust": false in your fledgling config to make it the default.

Usage

npx fledgling add [packages...] [options]

With no package arguments, add targets every public package in your workspace. Pass names or globs to narrow it down:

npx fledgling add my-pkg --yes              # one package
npx fledgling add "@scope/*" --yes          # a glob (quote it)
npx fledgling add "*-plugin" --yes          # all the plugins
npx fledgling add @scope/brand-new --new --yes   # claim a name that doesn't exist locally yet

Running bare npx fledgling (no subcommand) in a terminal drops you into the same flow interactively.

Run options

Flag	Description
-y, --yes	Apply changes without prompting (default in a terminal is the interactive wizard)
--dry-run	Print a plan without prompting (non-interactive)
--new	Treat unmatched names as brand-new packages to claim (squat a name)
--skip-publish	Only set up trusted publishing
--skip-trust	Only claim names
--force	Replace an existing trusted publisher (revoke + re-create)
--placeholder-version <v>	Placeholder version (default: 0.0.0)
--tag <tag>	dist-tag for placeholders (default: latest)
--otp <code>	npm 2FA one-time password, used for every npm call this run
--otp-secret <secret>	TOTP secret to generate 2FA codes from as needed (also $FLEDGLING_OTP_SECRET)

2FA / one-time passwords

npm requires 2FA to claim names and configure trusted publishing. By default fledgling just lets npm handle it interactively — it opens your browser to approve, and caches that approval for ~5 minutes, so one approval covers the whole run. When prompted, tick "don't ask again for 5 minutes" so it doesn't ask per-package.

For non-interactive runs (CI, scripts) there's no browser, so pass a code yourself:

• --otp <code> — a single one-time password, reused for every npm call in the run.
• --otp-secret <secret> — your authenticator's TOTP secret (base32); fledgling generates a fresh code for each npm call. Prefer the FLEDGLING_OTP_SECRET env var over the flag so the secret doesn't land in your shell history or process list.

Pull credentials straight from a password manager — e.g. 1Password's CLI (op). Read the generated code with ?attribute=otp and pass it to --otp:

fledgling sync --otp "$(op read "op://Private/npm/Security/one-time password?attribute=otp")"

…or read the secret itself — the field's value with no attribute, an otpauth:// URI — into FLEDGLING_OTP_SECRET, and fledgling mints a fresh code for every npm call:

FLEDGLING_OTP_SECRET="$(op read "op://Private/npm/Security/one-time password")" fledgling sync

Config flags

Better set once in package.json (see Configuration); as flags they override the config for that run.

Flag	Config key	Default
--provider <p>	provider	github
--permissions <p>	permissions	publish
--registry <url>	registry	npm config
--repo <owner/repo>	(auto-detected)	git origin
--workflow <file>	workflow	release.yml
--env <name>	environment	none
--org-id <uuid>	orgId	(circleci)
--project-id <uuid>	projectId	(circleci)
--pipeline-definition-id <uuid>	pipelineDefinitionId	(circleci)
--vcs-origin <origin>	vcsOrigin	(circleci)
--context-id <uuid>	contextIds	(circleci, repeatable)

What it does, precisely

For each target package:

1. Claim — if the name isn't on npm yet, publish a package.json-only placeholder (0.0.0, no code) to reserve it.
2. Trust — if there's no trusted publisher configured, set one up for your CI provider via npm trust (or replace an existing one with --force). Supports GitHub, GitLab, and CircleCI, with every option npm trust accepts.

Both steps are skipped when already done. Placeholders are packed from a throwaway temp dir, so your real package.json files are never touched.

fledgling sync — reconcile trusted publishing

Where the default command focuses on new packages (and hides already-published ones), fledgling sync reconciles trusted publishing across every package against your fledgling config.

It authenticates, reads each package's actual config on npm, and shows what's not configured or out of sync — with the exact difference (e.g. environment publish → (none)) — then asks before fixing it to match your config:

fledgling sync            # auth, check, then confirm + apply
fledgling sync --yes      # skip the confirm
fledgling sync "@scope/*" # a subset

Use it after changing your fledgling config, or to set up trust on packages that were published without it. (It uses the same config/flags as the main command.)

Shell completions

fledgling ships tab-completion (via @bomb.sh/tab) that completes package names and flags. Install it for your shell:

fledgling complete zsh  >> ~/.zshrc
fledgling complete bash >> ~/.bashrc
fledgling complete fish >  ~/.config/fish/completions/fledgling.fish

Then fledgling <TAB> completes the packages in your workspace.

Requirements

• Node ≥ 18
• npm ≥ 11.15.0 (for npm trust + OIDC/staged publishing)
• npm login with 2FA enabled for the trust step (npm requires it)

Supports npm / yarn / bun (workspaces) and pnpm (pnpm-workspace.yaml) monorepos, plus single-package repos.

License

MIT © DMNO Inc

---

fledgling is a creation of the team behind Varlock 🧙‍♂️
Check it out for secure secret sorcery — get your keys out of plaintext!