What you'll need

A Personal Access Token, generated from Nocerv → Paramètres → Nocerv CLI → + Générer un token. Copy it right away - it's shown once and never displayed again.

Install

npm install -g nocerv-cli

Connect

nocerv login

Paste your token when prompted - input is hidden as you type. You only do this once; the session is remembered on this machine.

Prefer not to type the token interactively?

# From a script or CI, piped in - never touches shell history
echo "$NOCERV_TOKEN" | nocerv login --token-stdin

# Inline - convenient, but visible in shell history and to other processes on the machine
nocerv login --token nocerv_pat_xxx

nocerv whoami   # check which account you're connected as
nocerv logout   # forget the saved session on this machine

Commands

nocerv knowledge list                    # your most recent knowledge
nocerv knowledge list --limit 10

nocerv knowledge search "title ..."     # keyword search
nocerv knowledge get [id]                # read one in full — pick from a list if id is omitted
nocerv knowledge delete [id]             # same picker, asks to confirm unless -y
nocerv knowledge create                  # capture a new one, fully interactive
nocerv knowledge create "title" --content "..."
nocerv knowledge update [id]             # edit one — every field pre-filled with its current value

nocerv collections list                  # your collections, with item counts
nocerv collections get [id]              # a collection and everything in it
nocerv collections create                # new collection, prompts for name/description
nocerv collections update [id]           # edit its name/description — current values pre-filled
nocerv collections add [collection-id] [knowledge-id]     # picks either one if omitted
nocerv collections remove [collection-id] [knowledge-id]
nocerv collections delete [id]           # asks to confirm unless -y

nocerv ingest ./docs                     # import every .md/.txt file in a folder
nocerv ingest ./docs/file-name.md           # import a single file
nocerv ingest ./docs --dry-run           # preview without sending anything

nocerv review                            # pick a deck interactively and review it
nocerv review <knowledge-id>             # review one deck directly
nocerv review --all                      # review every deck with pending cards

nocerv export                            # full backup, JSON, saved to ./nocerv-export.json
nocerv export --format zip               # same, as a .zip (adds a readable Markdown copy)
nocerv export -o ~/backups/nocerv.json

nocerv import backup.json                # restore a JSON backup — always adds, never overwrites
nocerv import backup.json --yes          # skip the confirmation (for scripts)

nocerv stats                             # the same numbers as the web app's Statistiques page

nocerv update                            # check right now if a newer version is available

nocerv completion bash                   # zsh, fish, powershell too — see "Shell completion" below

Capturing from the terminal

nocerv knowledge create "Docker cheatsheet" --content "docker compose up -d"
cat notes.md | nocerv knowledge create "Meeting notes"      # piped in
nocerv knowledge create                          # fully interactive, title included

In a real terminal, anything you don't pass as a flag/argument — including the title — is prompted for right there: title, then content (type or paste it, a real Enter submits, a pasted block — even one with blank lines in it — stays intact), then Type, Status and Category from an arrow-key list pulled from your actual account, then tags and a description, then a chance to attach one or more external links (a URL, not a file upload — for that see nocerv ingest). Anything you already passed ("title", --content, --type, --level, --category-id, --tags, --description) is used as-is and skipped in the prompts — mix and match freely, e.g. nocerv knowledge create "Docker cheatsheet" still prompts for everything except the title. Piped or scripted (no TTY), it's the opposite: no prompts ever, only what you passed — a missing title there is an error, not a hang. --level defaults to "New" if you don't set it, same as one created from the web app.

Editing an existing item

nocerv knowledge update                              # pick one, then edit it field by field
nocerv knowledge update <id> --level MASTERED         # change just one thing, no prompts
nocerv knowledge update <id> --tags ""                # clear every tag

Same shape as create, but every prompt starts pre-filled with the item's current value — press Enter to leave it as-is, or type over it to change it. Content is the one exception: rather than trying to "edit" a whole block of text in place inside a terminal, you're shown a short preview of what's there now and asked "Replace content? (y/n)" — say yes and you get the same type-or-paste prompt as create, which replaces it entirely. Nothing is sent to Nocerv for a field you left untouched, and if you don't change anything at all it just says "Nothing changed." instead of making a pointless request. Flags work the same way as create (--title, --content, --description, --category-id, --tags, --type, --level) - pass one to skip its prompt, or run entirely non-interactively with just flags.

Picking things by id

Anywhere a command needs an id — knowledge get, knowledge delete, collections get, collections add/remove, collections delete — the id is optional in a real terminal: leave it off and you get a searchable list pulled from your own account instead of having to already know or go dig up a UUID. Type to filter, arrow keys to move, Enter to pick. Piped or scripted, the id becomes required again — there's no one there to answer a prompt.

Collections

nocerv collections create "Interview prep"
nocerv collections update                   # prompts for which one, then name/description
nocerv collections add                      # prompts for both the collection and the item
nocerv collections get                       # prompts for which collection

add/remove only change which collection a knowledge item belongs to — the item itself is never touched, and collections delete removes the collection, not what was in it. Deleting asks "Delete this collection? (y/n)" first unless you pass -y/--yes (for scripts). update works the same way as knowledge update — name and description start pre-filled with their current value, press Enter to keep either as-is, --name/--description skip a prompt (--description "" clears it), and nothing is sent if you don't actually change anything.

Backups

nocerv export is the same backup the web app's Paramètres page produces — categories, tags, collections, knowledge, flashcards, attachments (embedded as base64 inside the file itself, not separate files). --format zip adds a plain-Markdown copy alongside, handy for browsing a backup without re-importing it anywhere. No arguments needed for a script: nocerv export -o "backup-$(date +%F).zip" --format zip in a cron job is the whole thing. Attachments over 60 MB combined are skipped rather than failing the export — same limit the web app uses.

Restoring a backup

nocerv import backup.json

Takes the JSON file nocerv export produces (the .json file, not .zip - a zip is a browsable extra for humans, not a valid import shape, and is rejected with a clear message if you point import at one directly). It shows a quick summary of what's inside before doing anything, then asks you to confirm (skip with -y/--yes for a script). Every import creates brand-new records - it has no way to know a knowledge item already exists and update it in place, so running the same file twice gives you two of everything. Useful for restoring after starting fresh, or moving a backup into a different account - not for keeping two accounts in sync.

Statistics

nocerv stats

The same numbers as the web app's "Statistiques" page, computed server-side so it's always consistent with what you'd see there: total count, activity over the last 7/30 days, favorites, collections, attachments and flashcard decks, a breakdown by status and by type (each with a little bar so it's readable at a glance), and your top categories and tags.

Reviewing flashcards

nocerv review runs a spaced-repetition session right in your terminal: it shows a question, waits for Enter to reveal the answer, then a single keypress marks it -

y  correct        n  needs more review        s  skip        q  stop and see the summary

Run without an id and it scans your decks for anything not yet marked correct and lets you pick one; --all goes through every deck with pending cards back to back. Results are saved back to Nocerv immediately, card by card - closing the session early (q or Ctrl+C) keeps everything you've already answered.

npm install -g doesn't auto-update an existing install. Nocerv CLI checks for a newer version at most once a day (cached, never adds noticeable delay) and prints a note after a command if one is available - never before, never mixed into your command's actual output. Update anytime with:

npm install -g nocerv-cli@latest

Shell completion

Tab-complete commands, subcommands and flags — nocerv kno<Tab> → knowledge, then nocerv knowledge <Tab> → list search get create delete, and so on into each subcommand's own flags. It's a one-time setup.

What you're actually doing. Every shell (bash, zsh, fish, PowerShell) has a small script file called a profile (or "rc file") that it runs automatically, every single time you open a new terminal window. Setup here means adding one line to that file — the line asks nocerv to print a completion script and has the shell load it immediately. Once that line is in your profile, tab completion "just works" in every future terminal, forever, with nothing else to run.

nocerv completion <shell> itself only ever prints that raw script — nothing else, no explanatory text. That's deliberate: since this runs from inside your profile on every terminal you open, any extra output would mean seeing a wall of "how to install this" instructions every time, forever, long after you've already installed it. All the explaining happens here, once.

PowerShell (Windows)

# 1. Does a profile file already exist? (this just checks — nothing is created yet)
Test-Path $PROFILE

# 2. If step 1 printed "False", create one:
New-Item -ItemType File -Path $PROFILE -Force

# 3. Open it in Notepad:
notepad $PROFILE

# 4. In Notepad, paste this on its own line, then save and close:
nocerv completion powershell | Out-String | Invoke-Expression

# 5. Load it into the current window without having to reopen a new one:
. $PROFILE

From here on, every new PowerShell window has completion — you won't see any output from this, it happens silently in the background before your first prompt.

bash

echo 'eval "$(nocerv completion bash)"' >> ~/.bashrc

Add that line to ~/.bashrc (the command above appends it for you), then open a new terminal.

zsh

nocerv completion zsh > "${fpath[1]}/_nocerv"

Run this once — it saves the script as a file named _nocerv in a folder zsh already scans for completions (no profile edit needed), as long as it runs above any compinit line already in ~/.zshrc. Open a new terminal afterwards.

fish

nocerv completion fish > ~/.config/fish/completions/nocerv.fish

Run once — fish picks up files in that folder automatically, no restart needed, nothing to add to a profile.

Checking it worked

Type nocerv kno in a new terminal window (the profile only runs when a terminal starts, so an already-open one won't have it) and press Tab. It should complete to nocerv knowledge. If nothing happens, double check the line landed in the right file and that you opened a genuinely new window afterward.

Where your session lives

~/.nocerv/
├── config.json        # the API URL you connected to
└── credentials.json   # your token - never shared, never logged

Always in your home directory, never inside a project folder. On Linux/macOS these files are locked to your user only (0700 for the folder, 0600 for credentials.json). Windows has no equivalent file-permission system, so protection there depends on your own Windows account.

Troubleshooting

• "Session expired or token revoked." - generate a new token from Nocerv → Paramètres and run nocerv login again.
• "Not found." / "Invalid request." / other API errors - the reason from the server, when available, is shown in parentheses after the message.
• nocerv ingest looks stuck - each file shows a spinner and a [N/total] counter while it uploads; on a slow connection or a large file this can take a while before the checkmark appears.

Running your own Nocerv instance

By default nocerv login connects to the public Nocerv instance - most people never need to think about this section. If you self-host your own instance instead, point the CLI at it:

nocerv login --api-url https://your-instance.example.com

Or set it once so you never have to pass the flag again:

export NOCERV_API_URL=https://your-instance.example.com   # ~/.bashrc, ~/.zshrc, etc.
# on Windows (PowerShell profile): $env:NOCERV_API_URL = "https://your-instance.example.com"