fledgling 🐣

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

Create and set up packages on npm with trusted publishing.

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.

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.

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 one-time password

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.10 (for npm trust)
• 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!