How to use NordPass CLI

Introduction

The NordPass CLI lets you work with your vault from a terminal. This guide will explain how to manage vault items and personal folders, read shared folders, manage trash, generate passwords, and pass secrets to other programs without ever writing them to a file.

Before you start

• Install the NordPass CLI by following our guides for macOS, Windows, and Linux.

Here's what to do

How to set your privacy choices

The first time you run the CLI, it asks two questions before anything else:

• Share usage data? Which commands are run, errors, the version, and your operating system. We never collect your passwords, usernames, or vault data.
• Share marketing data? Helps us measure how relevant our campaigns are and tailor what we send you. Turning it off does not change your notification preferences. Two service providers are involved: AppsFlyer, which measures and analyzes how you engage with our marketing campaigns, and Braze, which adapts and delivers tailored messages to you in real time.

Answer each with “Yes” or “No”. Your answers are saved on this device, and the marketing answer is also applied to your NordPass account. Only np -help and np --version run without asking. Every other command waits for an answer, including np item --help.

You can change either answer at any time:

If your vault is locked when you run it, the CLI saves your choice on this device and asks you to run np unlock followed by np consent again so the change reaches your account. The command needs a terminal, so it cannot run in a script or a pipeline.

How to get around

Every command has built-in help, so you never need to memorize this page:

1. np --help               # all commands
2. np item --help          # everything under "item"
3. np item create --help   # options for one command

Additionally, commands are grouped by what they act on:

How to get access

NordPass separates "Signing in" from "Unlocking your vault" - exactly as the Desktop and Web apps do:

1. np signin # opens your browser to sign in to your NordPass account 
2. np unlock # unlocks the vault so items can be decrypted

The np signin command opens your default browser. Sign in there, and the browser hands control back to the CLI automatically. If the browser cannot be opened, the CLI tells you and prints the URL so you can open it yourself.

Your vault stays unlocked between commands, so you do not re-enter your password for each one. It locks itself after 15 minutes without any CLI activity, and every command resets that timer — so if you are working continuously, it stays open. You can lock it immediately with the np lock command.

How to refer to items by name or by ID

Most commands accept either. Titles are matched without regard to capitalization, and must match exactly one item — if two items share the same title, the command stops and asks you to use the ID instead of guessing:

1. np item get "GitHub" 
2. np item get 550e8400-e29b-41d4-a716-446655440000

How to supply a secret

Any option that takes a secret value accepts all four of these methods. The last three keep the secret out of your shell history and out of the process list:

How to create machine-readable output

Add -- format json to any command that produces output, so you could pipe results into other tools:

np item list --format json | jq -r '.[].title'

How to work across several accounts

If you have more than one NordPass account signed in, --account runs a single command against a specific one without changing which account is active:

np --account alice@example.com item list

Session

How to keep the CLI up to date

The CLI can update itself. The np update command checks for a newer version, downloads the build for your operating system and processor, verifies that the download is intact, and replaces the installed program in place. It does not ask for confirmation, so it is safe to use in scripts. You stay signed in, and your vault is not affected:

If the CLI is installed in a folder you cannot write to, the command tells you. Run it again with the permissions needed for that folder, for example with sudo on macOS and Linux, or from a terminal opened as administrator on Windows. On Windows, the previous version stays next to the new one as np.exe.old until you run the CLI again, which removes it.

If you installed the CLI through a package manager rather than as a standalone program, np update does not replace it and tells you to update through that package manager instead.

Accounts

Items

When creating items, every item needs --type and --name. The remaining options depend on the type:

Custom fields take a Label=Value pair. Use --hidden-field for anything sensitive, so it is stored and displayed as a secret.

# A password item, prompting for the password rather than typing it inline 
np item create --type password --name "GitHub" --username "alice" --password

# A card, reading the security code from a prompt 
np item create --type card --name "Amex" --cardholder "Alice" \ --number "4111111111111111" --expiry "12/28" --cvv
 
# Custom fields, one visible and one hidden 
np item create --type password --name "AWS" \ --text-field "Account ID=123456" --hidden-field "Recovery=@code.txt"

# Copy just the password to your clipboard 
np item get "GitHub" --field password --copy

# Move an item to a different personal folder 
np item edit "GitHub" --folder "Work"

# Remove a custom field 
np item edit "AWS" --remove-field "Account ID"

# Delete everything in a personal folder, without prompts 
np item list --folder "Archive" --format json | jq -r '.[].id' | np item delete --yes

Folders

Deleting a personal folder that still contains items asks whether you want the items moved to Trash as well. Empty personal folders are deleted without asking. --trash-items answers that question in advance, which is what you want in a script.

If any of those items were shared with other people, deleting the folder also stops that sharing, and any reminders set on those items are cleared. Restoring the items from Trash does not restore the sharing.

Shared folders can be listed and their items read, but the CLI cannot create, rename, or delete a shared folder, and cannot move an item into one. Use the NordPass app for that.

If you pass a shared folder's name to --folder when creating or editing an item, the CLI reports that the folder was not found. The name is correct — the CLI simply does not place items into shared folders.

Trash

Generating passwords

--no-ambiguous leaves out characters that are easy to confuse, such as l, I, and 1.--count generates several at once.

How to use secrets in other programs

This is the part of the CLI that has no equivalent in the app. Instead of copying a password out of your vault into a .env file, you leave a reference in the file and let the CLI fill it in at the moment it is needed.

There are two ways to do it:

How to reference a secret

How to pass secrets to a program

# One secret, by item title
np run --env DB_PASSWORD="Production DB/password" -- your-command

# Several secrets, from a template file
np run --env-file .env.template -- your-command

A template file looks like an ordinary .env file, except the values are references rather than secrets, so it is safe to commit:

DB_USERNAME=item:550e8400-e29b-41d4-a716-446655440000/username 
DB_PASSWORD=item:550e8400-e29b-41d4-a716-446655440000/password 
API_KEY=Production API/custom:API_KEY

How to fill in a configuration file

or anything that is not an env file, np {{...}} placeholders in a template and render it:

database: 
  username: '{{Production DB/username}}' 
  password: '{{Production DB/password}}' 
  apiKey: '{{Production API/custom:API_KEY}}'

np inject --in config.template.yaml --out config.yaml 
np inject --env-file .env.template --out .env 
np inject --env-file .env.template --format json

How to get logs from CLI

CLI writes one log file per day and keeps it for 7 days:

In case you encounter any issues, follow these steps:

1. Run the failed command again.
2. Open the log folder.
3. Send the file to our customer support with today's date, for example: log_2026-09-09.log, 

Additional Tips

• Resolution is deliberately strict, so a script fails clearly rather than quietly using the wrong value:
  • A title must match exactly one item. If two items share it, the command stops and asks you to use the ID.
  • Items in Trash are never resolved.
  • np inejct command rejects duplicate keys in an env-style template; np run command silently uses the last value.
  • Duplicate keys in an env-style template are rejected.
  • A reference that cannot be found stops the command. --ignore-missing leaves it as-is instead.
    
    Note: -- ignore-missing exist only for the inject command.
     
• Deleting anything will ask if you wish to do so and show you the name of what is about to be affected. Add --yes when you are scripting to not receive the prompt.
• Once a secret has been passed to another program or written into a file, how it is handled is up to that program. Keep rendered files out of version control, and make sure your build system hides injected environment variables in its log. Here are the output formats:

# Several secrets, from a template file
np run --env-file .env.template -- your-command

DB_USERNAME=item:550e8400-e29b-41d4-a716-446655440000/username 
DB_PASSWORD=item:550e8400-e29b-41d4-a716-446655440000/password 
API_KEY=Production API/custom:API_KEY

database: 
  username: '{{Production DB/username}}' 
  password: '{{Production DB/password}}' 
  apiKey: '{{Production API/custom:API_KEY}}'

np inject --in config.template.yaml --out config.yaml 
np inject --env-file .env.template --out .env 
np inject --env-file .env.template --format json