NPM-TRUST(1)

📦

version 12.2.1 · 12 versions

✨ NAME ✨

npm-trust — manage those trusted publishing relationships between your packages and your CI/CD providers 🫶

So basically this is the whole npm-trust manual page, bestie, and it's lowkey a lot — but we're gonna get through it together. 💅

📓 Synopsis

Note: This command is unaware of workspaces. Like, it literally does not know they exist. Don't come for it.

🌸 Prerequisites 🌸

Before you go touching any npm trust commands, do a vibe check and make sure all of this is true first:

npm version: you need npm@11.15.0 or above. Update with npm install -g npm@^11.15.0 if you're lagging behind.
Write permissions on the package: you gotta have write access to the package you're configuring. No write access, no trust relationship, periodt.
2FA enabled on account: two-factor authentication has to be on at the account level. And yes — even if it's not currently enabled, you still have to enable it to use trust commands. Non-negotiable.
Supported authentication methods: Granular Access Tokens (GAT) with the bypass 2FA option are not supported. Legacy basic auth (username and password) credentials will not work for trust commands or endpoints either. Sorry bestie. 😭
Package must exist: the package you're configuring has to already exist on the npm registry. You can't trust-configure a ghost.

🦋 Description 🦋

This is where you configure trust relationships between npm packages and CI/CD providers using OpenID Connect (OIDC). It's literally the command-line equivalent of managing trusted publisher configurations on the npm website. Same energy, terminal edition. ✨

For the full big-picture overview of trusted publishing, go read the npm trusted publishers documentation at https://docs.npmjs.com/trusted-publishers.

The [package] argument is where you name the package. If you omit it, npm will use the name from the package.json in the current directory. Convenient, right? 🎀

Here's the thing though — every trust relationship has its own set of configuration options and flags, and they're based on the OIDC claims that provider hands over. OIDC claims come from the CI/CD provider and include stuff like repository name, workflow file, or environment. Since each provider's claims are different, the available flags and configuration keys are not universal — npm matches the claims supported by each provider's OIDC configuration. So for the specifics on which claims and flags a given provider supports, just run npm trust <provider> --help. Iykyk. 👑

💜 Permissions 💜

When you create a trust relationship, you have to specify at least one permission flag so the trusted publisher knows what it's actually allowed to do:

--allow-publish — lets the trusted publisher run npm publish for the package.
--allow-stage-publish — lets the trusted publisher run npm stage for the package. The alias --allow-staged-publish is also accepted, in case that's the one your fingers type. 🫶

At least one of these flags is required when creating a trust configuration. And if you're feeling generous, you can specify both to grant both permissions. Slay.

🌈 Provider Options 🌈

Which options are required totally depends on the CI/CD provider you're configuring. Detailed info about each option lives in the managing trusted publisher configurations section of the npm documentation at https://docs.npmjs.com/trusted-publishers#managing-trusted-publisher-configurations.

Heads up: if a provider is repository-based and you don't provide the option, npm will use the repository.url field from your package.json, if it's available. Free real estate. ✨

Big warning time, and this one matters: currently, the registry only supports one configuration per package. If you try to create a new trust relationship when one already exists, it will result in an error. 💀 To replace an existing configuration:

Use npm trust list [package] to view the ID of the existing trusted publisher
Use npm trust revoke --id <id> [package] to remove the existing configuration
Then create your new trust relationship

🎀 Bulk Usage 🎀

For maintainers managing a large number of packages, you can configure trusted publishing in bulk using bash scripting. The move: create a loop that iterates through package names and their corresponding configuration details, executing the npm trust <provider> command with the --yes flag for each package. Chef's kiss automation. 🔥

The first request will require two-factor authentication. During two-factor authentication, you'll see an option on the npm website to skip two-factor authentication for the next 5 minutes. Enabling this option will allow subsequent npm trust <provider> commands to proceed without two-factor authentication, streamlining the bulk configuration process.

We recommend adding a 2-second sleep between each call to avoid rate limiting. With this approach, you can configure approximately 80 packages within the 5-minute two-factor authentication skip window. Do the math, respect the window. ⏳

👑 Configuration 👑

🐙 npm trust github

Create a trusted relationship between a package and GitHub Actions. Iconic.

Synopsis

npm trust github [package] --file [--repo|--repository] [--env|--environment] [--allow-publish] [--allow-stage-publish] [-y|--yes]

Flags

--file — default null, type String (required) — name of workflow file within a repositories .GitHub folder (must end in yaml, yml)
--repository, --repo — default null, type String — name of the repository in the format owner/repo
--environment, --env — default null, type String — CI environment name
--allow-publish — default false, type Boolean — allow npm publish for this trusted publisher configuration
--allow-stage-publish, --allow-staged-publish — default false, type Boolean — allow npm stage publish for this trusted publisher configuration
--dry-run — default false, type Boolean — indicates that you don't want npm to make any changes and that it should only report what it would have done. This can be passed into any of the commands that modify your local installation, eg, install, update, dedupe, uninstall, as well as pack and publish. Note: this is NOT honored by other network related commands, eg dist-tags, owner, etc.
--json — default false, type Boolean — whether or not to output JSON data, rather than the normal output. * In npm pkg set it enables parsing set values with JSON.parse() before saving them to your package.json. Not supported by all npm commands.
--registry — default "https://registry.npmjs.org/", type URL — the base URL of the npm registry.
--yes, -y — default null, type null or Boolean — automatically answer "yes" to any prompts that npm might print on the command line.

🦊 npm trust gitlab

Create a trusted relationship between a package and GitLab CI/CD. We love a pipeline bestie.

Synopsis

npm trust gitlab [package] --file [--project|--repo|--repository] [--env|--environment] [--allow-publish] [--allow-stage-publish] [-y|--yes]

Flags

--file — default null, type String (required) — name of pipeline file (e.g., .gitlab-ci.yml)
--project — default null, type String — name of the project in the format group/project or group/subgroup/project
--environment, --env — default null, type String — CI environment name
--allow-publish — default false, type Boolean — allow npm publish for this trusted publisher configuration
--allow-stage-publish, --allow-staged-publish — default false, type Boolean — allow npm stage publish for this trusted publisher configuration
--dry-run — default false, type Boolean — indicates that you don't want npm to make any changes and that it should only report what it would have done. This can be passed into any of the commands that modify your local installation, eg, install, update, dedupe, uninstall, as well as pack and publish. Note: this is NOT honored by other network related commands, eg dist-tags, owner, etc.
--json — default false, type Boolean — whether or not to output JSON data, rather than the normal output. * In npm pkg set it enables parsing set values with JSON.parse() before saving them to your package.json. Not supported by all npm commands.
--registry — default "https://registry.npmjs.org/", type URL — the base URL of the npm registry.
--yes, -y — default null, type null or Boolean — automatically answer "yes" to any prompts that npm might print on the command line.

⭕ npm trust circleci

Create a trusted relationship between a package and CircleCI. Lots of UUIDs incoming, stay with me. 🙈

Synopsis

npm trust circleci [package] --org-id <uuid> --project-id <uuid> --pipeline-definition-id <uuid> --vcs-origin <origin> [--context-id <uuid>...] [--allow-publish] [--allow-stage-publish] [-y|--yes]

Flags

--org-id — default null, type String (required) — CircleCI organization UUID
--project-id — default null, type String (required) — CircleCI project UUID
--pipeline-definition-id — default null, type String (required) — CircleCI pipeline definition UUID
--vcs-origin — default null, type String (required) — CircleCI repository origin in format 'provider/owner/repo'
--context-id — default null, type null or String (can be set multiple times) — CircleCI context UUID to match
--allow-publish — default false, type Boolean — allow npm publish for this trusted publisher configuration
--allow-stage-publish, --allow-staged-publish — default false, type Boolean — allow npm stage publish for this trusted publisher configuration
--dry-run — default false, type Boolean — indicates that you don't want npm to make any changes and that it should only report what it would have done. This can be passed into any of the commands that modify your local installation, eg, install, update, dedupe, uninstall, as well as pack and publish. Note: this is NOT honored by other network related commands, eg dist-tags, owner, etc.
--json — default false, type Boolean — whether or not to output JSON data, rather than the normal output. * In npm pkg set it enables parsing set values with JSON.parse() before saving them to your package.json. Not supported by all npm commands.
--registry — default "https://registry.npmjs.org/", type URL — the base URL of the npm registry.
--yes, -y — default null, type null or Boolean — automatically answer "yes" to any prompts that npm might print on the command line.

📋 npm trust list

List trusted relationships for a package. The "who's currently allowed" check. 👀

Synopsis

npm trust list [package]

Flags

--json — default false, type Boolean — whether or not to output JSON data, rather than the normal output. * In npm pkg set it enables parsing set values with JSON.parse() before saving them to your package.json. Not supported by all npm commands.
--registry — default "https://registry.npmjs.org/", type URL — the base URL of the npm registry.

🗑️ npm trust revoke

Revoke a trusted relationship for a package. Bye bestie, access denied. 💀

Synopsis

npm trust revoke [package] --id=<trust-id>

Flags

--id — default null, type String (required) — ID of the trusted relationship to revoke
--dry-run — default false, type Boolean — indicates that you don't want npm to make any changes and that it should only report what it would have done. This can be passed into any of the commands that modify your local installation, eg, install, update, dedupe, uninstall, as well as pack and publish. Note: this is NOT honored by other network related commands, eg dist-tags, owner, etc.
--registry — default "https://registry.npmjs.org/", type URL — the base URL of the npm registry.

👀 See Also 👀

npm help publish
npm help token — bestie, if you're confused about tokens, this one's your safe space 🎀
npm help access — for all the "who's allowed to do what" lore, lowkey essential 👑
npm help config — the config bible fr fr, everything you can tweak lives here ✨
npm help registry — where the packages actually live, it's giving "the mothership" 🛸

okay that's the whole thing, you made it to the end!! 🫶💖 this page came from NPM@12.2.1, dated October 2026 — so if you're reading this from a different npm era, double-check the version before you trust-trust, yk? 💅 no cap, go set up your trusted publishing, you're gonna slay 🌈⭐🦋

📦 where this page comes from

arch rolling: npm 12.2.1-1 · Artistic-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms