Command-line reference

This page lists every command of the pangur command-line tool (version 0.3.3), grouped by what it works on. Installing the tool and signing in are covered in The command line. The tool's old name, zcp, still runs it, and some of its own messages still print zcp …, so either name works.

Run pangur --help, or pangur <command> --help, for the tool's own summary of a command. Running pangur with no command prints the help.

Conventions on this pageCopy Anchor Link

• KEY is an item's eight-character key, as pangur search prints it. ATTACHMENT is the key of a file attached to an item, as pangur get lists it.
• --json prints the server's JSON response, indented, in place of the usual table or text.
• --connection ID works in the named project, by its id or its address (see Project selection). A command without this option always works in your default project.
• --yes (or -y) answers yes to the command's confirmation question.
• Errors print to standard error as the HTTP status and the server's message, and the command exits with status 1.

AccountCopy Anchor Link

Reading your libraryCopy Anchor Link

Changing your libraryCopy Anchor Link

These commands change the library. edit and delete are available here and in the web app, but not to assistants.

Institutional access belongs to your account and applies in every project; see Where PDFs come from.

Adding worksCopy Anchor Link

pangur importCopy Anchor Link

pangur add IDENTIFIER is a shorter name for pangur import add, with the same options. pangur import lookup can also be run as pangur lookup.

The web app imports the same reading lists and reference files.

pangur ingestCopy Anchor Link

pangur ingest brings in files you already have. Pangur reads the first pages of each file for a DOI, ISBN or arXiv id, checks the library, and either creates a reference with the file attached, attaches the file to the existing item, or stores the file on its own until you say what it is.

The table that ingest files prints gives each file's outcome: matched, duplicate, needs_reference or failed. The command exits with status 1 if any file failed.

pangur refsCopy Anchor Link

pangur refs finds the works a document cites and imports them. Each reference it finds has one of four statuses: in_library, importable, primary_source (an archival manuscript, which cannot be imported) or unresolved.

Background workCopy Anchor Link

The same work appears on the Activity page in the web app.

Ask and conversationsCopy Anchor Link

DocumentsCopy Anchor Link

Despite its name, docs append does not add to the end of a document: pass the whole new text.

ExportingCopy Anchor Link

For what the project ZIP contains, see Export your work or delete your account.

BooksCopy Anchor Link

ManuscriptsCopy Anchor Link

In the web app the same work is done on the transcription desk, and the export formats are described in TEI texts and transcription exports.

Reading in order, copies and groupsCopy Anchor Link

A copy is a set of files that together show a resource, such as a scan or an afternoon's photographs, and the tools call it a surrogate set. Copies are managed in the web app as described in Manage copies and parts, and arrangements and source groups in Arrangements, source groups and vocabularies.

CorporaCopy Anchor Link

These commands work on analysis corpora. Several of them print JSON only.

The staging, activation and rollback of source inventories are explained in Source inventories and assistant-submitted analysis.

ExhibitionsCopy Anchor Link

Publishing is not offered on every account or deployment. What publishing does, and how many exhibitions each plan keeps live, are set out in Publish, protect and take down an exhibition.

Project selectionCopy Anchor Link

A command with --connection works in the project you name by its id or address, both of which pangur projects lists. Without --connection, the server uses your default project, which is the one you opened last on any device. If a personal project and an organisation project share an address, the personal one is used.

These commands have no --connection option and always work in the default project:

• overview, search, get, read, cite, collections and tags;
• edit, delete, note and upload;
• import search and import lookup (import add, import refs and import file do take --connection);
• the book commands;
• the refs commands, except refs import;
• exhibitions show, exhibitions publish and exhibitions unpublish, which find the exhibition by its id.

institution, tasks and jobs belong to your account and cover every project. To run one of the default-project commands in another project, open that project in Pangur first.

If the project is scoped to one collection, every command sees only that collection and files new items into it. A viewer in an organisation project can read, ask and export, and every command that changes the project is refused.

Commands that use Pangur's modelCopy Anchor Link

Only two commands run Pangur's model and count against your allowances:

• pangur ask without --materials counts as an Ask question on your plan and uses your daily model allowance.
• pangur manuscript transcribe reads the leaf twice with the vision model and counts against the daily limit on manuscript transcriptions.

The citation scans behind pangur refs and pangur import refs may also use the model while they refine a scan in the background, within your daily model allowance. Every other command runs no model. The allowances themselves are set out in Plans, limits and usage.

Environment variablesCopy Anchor Link

All of these are optional, and the defaults point at pangur.io.

The command has no configuration file other than the credentials file, and no variable for a default project or output format.