The command line

The pangur command is Pangur's command-line tool. It uses the same account and the same projects as the web app, and from a terminal it can do most of what you do in the library: search and read your sources, format citations, import references and files, ask questions, export, and transcribe manuscript leaves. Because most commands can print the server's JSON, it is also convenient in scripts.

The command used to be called zcp, and zcp still works as a second name for it. Some of the messages the tool prints still use the old name.

This page takes you from installation to your first commands. Every command and option is listed in the command-line reference.

How the command line differs from an assistantCopy Anchor Link

The command line is a tool you operate yourself, so Pangur treats it like the web app rather than like an assistant. It can edit and delete: pangur edit changes an item's fields, pangur delete removes an item with its notes and files, and pangur threads delete removes an Ask conversation, none of which an assistant can do. It also runs Pangur's model when you ask it to. pangur ask writes an answer with Pangur's model and counts against your plan's Ask allowance, just as Ask on the web does, whereas pangur ask --materials returns the passages only, runs no model and uses no allowance. pangur manuscript transcribe reads a leaf with Pangur's vision model and counts against the daily limit on transcriptions. The limits are set out in Plans, limits and usage.

Installing the commandCopy Anchor Link

The command needs Python 3.10 or later, which the installer can arrange for you. Run the install line that Pangur shows under Settings → Assistants and command line → Command line:

curl -fsSL https://updates.pangur.io/pangur-cli/updates/install.sh | sh

The script downloads the latest release and installs it with the first of these tools it finds on your machine: uv (which fetches a suitable Python itself if it has to), then pipx, then Python 3.10 or later with pip. If none of them is present, it stops and tells you which one to install. The script needs curl and a POSIX shell, which macOS and Linux provide.

When it finishes, the script tells you to run pangur login. If it says instead that pangur is not on your PATH yet, add ~/.local/bin to your PATH as it describes, open a new terminal, and carry on from there.

To update, run the same line again, which reinstalls the latest release over the old one. The script prints the version it installs. Note that the command itself has no --version option.

On a Mac with Pangur for MacCopy Anchor Link

Pangur for Mac carries its own copy of the command and installs it for you. When the app launches, it writes small pangur and zcp scripts into ~/.local/bin that run the copy inside the app, so updating the app also updates the command. On first install it adds ~/.local/bin to your PATH in your shell profile, unless a profile already has it. If you installed a pangur command some other way, the app leaves that one alone.

The command keeps its own sign-in, separate from the app's, so you still need to run pangur login once on the Mac.

Removing the commandCopy Anchor Link

Remove the command with the tool that installed it, for example uv tool uninstall pangur-cli or pipx uninstall pangur-cli. Your sign-in lives in ~/.config/zcp/credentials.json, so run pangur logout first if you want the sign-in gone as well.

Signing inCopy Anchor Link

Run:

pangur login

By default, pangur login uses a device code, so it works on a machine without a browser, such as a server you reach over SSH. It prints two lines:

Open  https://auth.pangur.io/realms/zcp/device?user_code=…
Code  ABCD-EFGH

Open the address on any device, sign in to Pangur, and confirm the code. The command waits until you do and then reports that you are logged in. If you take too long, the code expires and the command stops with "login timed out — code expired"; run pangur login again.

On a machine with a browser, pangur login --browser opens the sign-in page in your default browser instead and returns to the terminal once you have signed in. The browser tab then tells you that you can close it.

To check who you are signed in as, run pangur whoami. It prints your email address and your projects, marks the default project, and shows for each project whether assistants and the command line see the whole library or one collection.

How the sign-in is keptCopy Anchor Link

The command saves its sign-in in ~/.config/zcp/credentials.json, a file it creates readable only by you on macOS and Linux. It does not use the system keychain. The saved sign-in renews itself as you use the command. If it can no longer be renewed, commands stop with "session expired — run pangur login again", and you sign in again.

pangur logout ends the session on Pangur's sign-in service and then deletes that file. If the sign-in service cannot be reached, the file is still deleted, the command says so, and the session ends when it expires.

The command keeps one sign-in at a time. To keep sign-ins for two accounts, point the ZCP_CREDENTIALS environment variable at a different file for each, as described under Environment variables.

First commandsCopy Anchor Link

These commands work in your default project and show the main kinds of work the tool does.

pangur search "prophecy"

This searches your library's titles and other details, such as creators, tags and abstracts, and prints a table of keys, titles, creators, years and types. It does not search the text inside your files; for that, ask a question with pangur ask. Every word has to match, so if nothing comes back, try fewer words.

pangur get ABCD1234

This prints one item's full details, with its attachments and notes. The eight-character key comes from the search results.

pangur read ABCD1234 --all

This prints the readable text of the item's first readable attachment (you can also give an attachment key). Without --all, it prints one window of text and tells you the offset to continue from.

pangur cite ABCD1234 EFGH5678 --style chicago-author-date

This prints a formatted bibliography in any CSL style, with apa as the default. Add --json for CSL-JSON instead.

pangur add 10.1017/S0018246X00012345

This adds a work by DOI or ISBN and tries to attach its PDF. If the work is already in your library, the command asks before saving a duplicate, and if the PDF search carries on in the background, it tells you to follow it with pangur tasks.

pangur ask "What do my sources say about the Camisard prophets?"

This asks your library a question, as Ask does on the web. The answer streams into the terminal, followed by its numbered sources and a conversation ID that you can pass to --thread to ask a follow-up.

Working in another projectCopy Anchor Link

Commands that take --connection work in the project you name, by its id or its address. pangur projects lists your projects with their addresses, their organisations and your role in each. An organisation project's address contains a dot, as in edinburgh-history.letter-books.

pangur projects
pangur ask --connection huguenot-letters "Who wrote from Geneva in 1686?"

Without --connection, a command uses your default project, which is the project you opened last in Pangur. Several commands have no --connection option and always use the default project, among them search, get, read, cite, edit and delete (the full list is under Project selection in the reference). To run one of those in another project, open that project in Pangur first.

If the project is scoped to one collection, the command line sees only that collection, exactly as an assistant does. The rules are under Scope to one collection.

Using the command in scriptsCopy Anchor Link

Most commands accept --json and then print the server's JSON response, indented, in place of a table. Errors go to standard error as the HTTP status and the server's message, and the command exits with status 1.

Commands that would delete or import ask for confirmation first, and --yes (or -y) skips the question. pangur delete ABCD1234 --yes, for example, deletes without asking.

The environment variables ZCP_API_BASE, ZCP_ISSUER and ZCP_CREDENTIALS point the command at another Pangur server, sign-in service or credentials file. The defaults are for pangur.io.