Contents

The prem command

Every prem command with its arguments and options, in the program's own words. prem --help prints all of it, prem <command> --help prints one command's part, and a command called with a subcommand or an option it does not take prints its part and exits 1. For a built-in command none of these needs a database; for a command an extension adds, they are answered once the extensions load, which needs one. This page is generated by prem help --markdown, and a test fails when the page and the program differ.

The database a command uses, and the embedding provider, come from the environment; the variables are listed at the end of this page and on Configuration.

01Who may read, in the program's words

shell01
Who may read a document is decided by folder rules (prem rules), and a
folder no rule covers is readable by nobody. Search defaults to what
everyone may read. There is no flag that quietly widens either one.

02Asking the program

shell02
PremAgentic CLI: governed retrieval over an organization's own documents.

prem --help                (also prem -h and prem help) this text
prem <command> --help      (also prem help <command>) one command's part of it
prem --version             the version, with the commit it was built from
prem help --markdown       this text as the manual page, docs/cli.md

03prem migrate

The schema this build carries.

shell03
prem migrate
prem init-db

  Applies the numbered migrations this build carries, or says the schema is current, and makes
  sure the tenant exists. Every other command does the same before it runs. init-db is another
  name for migrate.

04prem setup

Installs the database side of PremAgentic on a PostgreSQL that already exists.

shell04
prem setup [--plan] [--database name] [--owner-role name] [--app-role name] [--search-role name]
             [--credentials-dir dir] [--admin-connection-file file]
             [--admin-user name] [--admin-password-file file]
             [--host-name name] [--https-port port]
             [--windows-service] [--api-path file]
             [--bundled-postgres folder --data-dir folder [--postgres-port port]]

Installs PremAgentic on a PostgreSQL that already exists (14 or later), then
searches as the application role to prove it works. Safe to run again: a
finished install is left as it is, and a half-finished one is completed.

  --plan                   report every step and change nothing
  --database name          the database to create or use (default: premagentic)
  --owner-role name        owns the schema; runs migrations and rebuild-index (default: premagentic_owner)
  --app-role name          reads and writes rows, nothing else (default: premagentic_app)
  --search-role name       reads documents and chunks for a caller, nothing else (default: premagentic_search)
  --credentials-dir dir    where the credentials files, the HTTPS certificate and its settings are
                           written (default: the Premagentic folder in this account's local application
                           data, or C:\ProgramData\Premagentic with --windows-service)
  --admin-connection-file  a file holding a line connection=<connection string> for a role that
                           can create roles and databases
  --admin-user name        make this sign-in name the first administrator, when no administrator
                           exists yet. Its password is asked for, or read from --admin-password-file
  --admin-password-file    a file whose first line is the first administrator's password
  --host-name name         the name clients use for the API; the self-signed HTTPS certificate is
                           made for it (default: this computer's name)
  --https-port port        the API's HTTPS port (default: 8443)
  --windows-service        register the API as the Windows service Premagentic, under its own
                           virtual account (needs an elevated prompt; the service is not started)
  --api-path file          the API program the service runs (default: Premagentic.Api.exe beside prem)
  --bundled-postgres dir   the pgsql folder of the PostgreSQL bundled with PremAgentic on Windows. Setup
                           makes a cluster in --data-dir, listening on localhost only, starts it (as a
                           service with --windows-service), and uses its superuser instead of an admin
                           connection. The superuser's password goes to postgres.credentials, readable by
                           this account and administrators only. Needs the Visual C++ 2015 to 2022 x64 runtime
  --data-dir dir           where the bundled server keeps its data (default: the Premagentic folder in
                           C:\ProgramData with --windows-service, else in this account's application data)
  --postgres-port port     the bundled server's port on localhost (default: 5432)

The admin connection comes from --admin-connection-file or from
PREM_SETUP_ADMIN_CONNECTION. Generated passwords are written only to the
credentials files and the HTTPS settings, and are never printed. Point the
application at its file with PREM_CREDENTIALS_FILE; point it at
owner.credentials only to migrate or rebuild the index. Every connection
setup writes uses GSS Encryption Mode=Disable unless the admin connection
sets that key itself.

05prem remove

Takes away what setup registered, and keeps the data unless told otherwise.

shell05
prem remove [--plan] [--purge [--yes]] [--credentials-dir dir] [--windows-service]
            [--admin-connection-file file] [--bundled-postgres folder] [--data-dir folder]

Takes away what prem setup registered, and keeps the data. The Windows
services Premagentic and PremagenticDb are stopped and removed where they
exist (from an elevated prompt); on Linux the systemd steps are printed for
root to run. The database, its three roles, the credentials files and a
bundled server's data folder all stay, so prem setup run again uses them.

  --plan                   report every step and change nothing
  --purge                  delete the data as well: drop the database as its owner, from owner.credentials,
                           and the three roles as the admin role, stop the bundled server and delete its data
                           folder, then delete the credentials files. Every document, user, setting and the
                           audit trail goes, and it cannot be undone
  --yes                    carry out --purge; without it the purge is listed and nothing is changed
  --credentials-dir dir    where setup wrote the credentials files (default: as for prem setup)
  --windows-service        the install was made with --windows-service, so the defaults are in C:\ProgramData
  --admin-connection-file  a file holding a line connection=<connection string> for a role that can drop
                           roles, for --purge on a PostgreSQL that existed before PremAgentic. The owner
                           cannot: setup makes it without that right. A bundled server's superuser is read
                           from postgres.credentials instead
  --bundled-postgres dir   the pgsql folder of the bundled PostgreSQL, to stop a server started by hand
  --data-dir dir           the bundled server's data folder (default: as for prem setup, when the install
                           has a bundled server)

The admin connection comes from --admin-connection-file or from
PREM_SETUP_ADMIN_CONNECTION, as for setup, and is never printed.

06prem rebuild-index

Empties the index so every source can be ingested again.

shell06
prem rebuild-index --confirm

  Empties every index table so the next ingest of each source rebuilds it. Users, settings and the
  audit trail are not touched. Search returns nothing until each source is ingested again.

  --confirm              required; without it nothing is emptied

07prem ingest

Reads a folder, or a registered source, into the index.

shell07
prem ingest <folder> [--public | --principals a,b | --entry "allow group:Staff" ...] [--prefix p]
                     [--okf-bundle] [--undeclared-as-machine] [--chunker name] [--allow-empty-source]
                     [--remove-unread]
prem ingest --source <name> [--allow-empty-source] [--remove-unread]

  Reads a folder into the index: its documents are cut into chunks, embedded on this computer and
  stored, and the ones gone from the folder are removed. A folder given by hand is read with the
  flags given and registers nothing; --source reads a registered source (prem sources) with its
  own folder, prefix and settings. The run is recorded either way. Who may read the documents is
  decided by the folder rules, and a folder no rule covers is refused.

  --public               set this folder's rule to allow everyone, then ingest
  --principals a,b       set this folder's rule to allow these principals, then ingest. Principals
                         are written by name: group:Staff, user:alice, everyone
  --entry "..."          set this folder's rule from these entries, one --entry each, in order,
                         then ingest
  --prefix p             the path the documents are indexed under (default: none)
  --okf-bundle           read the folder as an Open Knowledge Format bundle
  --undeclared-as-machine  in a bundle, treat a concept that does not say who wrote it as machine
                         written and unverified, so agents do not see it until a person signs it off
  --chunker name         how documents are cut into chunks (default: markdown; prem sources
                         chunkers lists the others)
  --source name          read the registered source with this name; only --allow-empty-source
                         and --remove-unread may be added
  --allow-empty-source   permit deleting every indexed document under the prefix when the folder
                         yields nothing. Off by default, because an unmounted volume or a revoked
                         permission looks exactly like an emptied folder
  --remove-unread        remove documents indexed earlier in a format no reader here reads now.
                         Off by default: they are kept and counted, so a reader that was refused
                         or disallowed costs nothing that was indexed

Searches as one caller.

shell08
prem search "<query>" [--user name | --with-token | --as a,b | --unrestricted reason] [--historical] [--top N]

  Searches the index as one caller and prints the passages that caller may read, best first, each
  with its citation, its trust, its authorship and whether it is stale.

  --user name            as this PremAgentic user, with the user's groups as they are now
  --with-token           as the agent whose token is read from standard input or a prompt, never
                         from an argument, with that agent's trust policy
  --as a,b               as a caller holding these principals, by name: group:Staff, user:alice
  --unrestricted reason  past the access gate; the reason is recorded on the event. Give at most
                         one of --user, --with-token, --as and --unrestricted; with none, only what
                         everyone may read
  --historical           include superseded and archived documents
  --top N                how many passages to print (default: 5)

09prem section

Reads one document, or one section of it, as one caller.

shell09
prem section <path> [heading] [--user name | --with-token | --as a,b | --unrestricted reason] [--historical]

  Prints one indexed document, or its section under a heading, when the caller may read it.

  --user name            as this PremAgentic user, with the user's groups as they are now
  --with-token           as the agent whose token is read from standard input or a prompt, never
                         from an argument, with that agent's trust policy
  --as a,b               as a caller holding these principals, by name: group:Staff, user:alice
  --unrestricted reason  past the access gate; the reason is recorded on the event. Give at most
                         one of --user, --with-token, --as and --unrestricted; with none, only what
                         everyone may read
  --historical           allow a superseded or archived document

10prem eval

Runs a golden set against the index.

shell10
prem eval <golden-questions.json> [report-path]

  Runs a golden set: each question is searched as the caller it names, under the tuning the
  deployment has stored, and the passages it expects, forbids and expects to be absent are checked.
  Writes a Markdown report and says where (default: report-<date>.md in the current folder), never
  into a folder that holds a profile, and exits 1 when any question fails.

11prem users

The people who sign in.

shell11
prem users add <sign-in-name> [--display "Name"] [--role administrator|auditor|member]
               [--password | --password-file <file>]
prem users disable|enable <sign-in-name>
prem users set-password <sign-in-name> [--password-file <file>]
prem users list

  The people who sign in. A disabled user, and every agent the user owns, reaches nothing.

  A password is never an argument: a script names a file, or pipes the password on standard
  input, and a person types it at a prompt that does not echo.

  --display "Name"       add: the name the portal shows (default: the sign-in name)
  --role r               add: administrator, auditor or member (default: member)
  --password             add: read a password from standard input or a prompt; without it or
                         --password-file the user has no password until set-password gives one
  --password-file file   add, set-password: the password is the only line of this file, which
                         is only read; standard input is not read and nothing is asked

12prem groups

Groups of people.

shell12
prem groups add <name>
prem groups rename <name> <new-name>
prem groups remove <name> [--force]
prem groups members <name> [--add a,b] [--remove c,d]
prem groups list

  Groups of people, which folder rules name by name and store by id, so a rename leaves every rule
  as it was.

  --force                remove: remove a group that rules name. A deny entry for it then matches
                         nobody, which can widen who reads those folders
  --add a,b              members: add these users, by sign-in name
  --remove c,d           members: take these users out

13prem agents

The agents that read with a token.

shell13
prem agents add <name> --owner <sign-in-name> --mode acts-for-user|service --model local|hosted
                [--vendor "Name"] [--rate N] [--min-trust tier]
prem agents set <name> --model local|hosted [--vendor "Name"]
prem agents disable|enable <name>
prem agents remove <name>
prem agents grant|ungrant <agent> <group>
prem agents list [--removed]

  Agents read with a token and never write. One that acts for its owner reads as the owner and
  never more; a service agent reads as itself and the groups it is granted.

  A removed agent's tokens are revoked, its grant ends, and it is gone from every list. Nothing
  is deleted: the change record, the audit and the usage still name it, and its name is free for
  a new agent.

  --owner name           add: the user responsible for the agent
  --mode m               add: acts-for-user or service
  --model where          add, set: local (the model runs inside your network) or hosted (it runs
                         on someone else's). There is no default. An agent on a hosted model is
                         in the reserved group of hosted-model agents, which a folder rule can deny
  --vendor "Name"        add, set: who runs a hosted model
  --rate N               add: requests per minute (default: 60)
  --min-trust tier       add: the lowest trust tier the agent is served (default: the deployment's)
  --removed              list: the removed agents instead, with when and by whom

14prem tokens

Agent tokens.

shell14
prem tokens issue <agent> [--days N]
prem tokens reissue <token-id> [--days N]
prem tokens reissue --agent <agent> [--days N]
prem tokens revoke <token-id>
prem tokens list [<agent>]

  An agent's tokens. A token is printed once, when it is issued, and cannot be recovered; a
  revoked token reaches nothing on its next call.

  A reissue replaces a live token in one change: the new token is printed once and the old one
  is revoked, both or neither. It never brings a key back: a disabled agent or person, and a
  revoked, expired or ended token, are refused.

  --days N               issue: how long the token lasts, 1 to 3650 (default: 90); reissue: the
                         same (default: the replaced token's own lifetime, counted from now)
  --agent name           reissue: the agent's one live token, when it has exactly one

15prem oauth

The assistants that connect through the MCP authorization flow, and their grants.

shell15
prem oauth clients list
prem oauth clients add <name> --redirect <address> [--redirect <address> ...] [--id <https-address>]
                       [--model local|hosted] [--vendor "Name"]
prem oauth clients add --metadata-file <path> --id <https-address> [--model local|hosted] [--vendor "Name"]
prem oauth clients replace --metadata-file <path> --id <https-address>
prem oauth clients disable|enable|remove <client-id>
prem oauth grants list [--user <sign-in-name>] [--all]
prem oauth grants revoke <grant-id> | --user <sign-in-name> | --all

  The assistants that connect through the MCP authorization flow, and the grants people approved for
  them. Each grant reads through an agent that acts for the person who approved it, and never writes.
  Disabling or removing a client ends its grants and disables their agents; enabling it again brings
  none back. Replacing a client's metadata document, when its vendor has changed it, keeps every grant;
  its name and redirect addresses come from the new copy, and a code is exchanged only for an address
  the new copy lists. These commands work whether the flow is on or off.

  --redirect address     clients add: where the flow may send its answer: https, or http to 127.0.0.1,
                         [::1] or localhost. Give one to five
  --id address           clients add: the https address an assistant names itself by, for one set
                         up with it (default: a new prem_cli_ id, printed)
  --metadata-file path   clients add, replace: a copy of the metadata document that address names, saved
                         by hand, at most 64 KB. Its client_id must be the --id address exactly; the name
                         and redirect addresses come from it; nothing is fetched from the address
  --model where          clients add: local or hosted, where the assistant's model runs. The consent
                         page then says so instead of asking each person
  --vendor "Name"        clients add: who runs a hosted model; required with --model hosted
  --user name            grants list, revoke: one person's grants
  --all                  grants list: ended grants too (default: live ones only); grants revoke: every
                         grant not yet revoked

16prem rules

Folder rules: who may read what.

shell16
prem rules set [--source s] [--prefix p] (--public | --principals a,b | --entry "allow group:Staff" ...)
prem rules remove [--source s] [--prefix p]
prem rules list

  A folder rule decides who may read the documents under its prefix, and the longest prefix wins.
  Its list is read in order and the first entry that names the caller decides; no match is a deny.

  --source s             the source the rule is for (default: filesystem, which prem ingest reads
                         folders as)
  --prefix p             the path prefix the rule covers (default: the whole source)
  --public               set: allow everyone
  --principals a,b       set: allow these principals, by name: group:Staff, user:alice, everyone
  --entry "..."          set: one entry of the list, such as "deny group:Contractors"; give one
                         --entry for each, in order

17prem settings

The deployment's settings and the change record.

shell17
prem settings list
prem settings get <key>
prem settings set <key> <value>
prem settings unset <key>
prem settings history [--limit N]

  The deployment's settings, and the change record every change is written to. list shows every
  key the deployment defines, and get says what one does and what it accepts. set takes JSON,
  such as 40, 0.5 or {"default": 1.0}, except for a path or a trust value, which is plain text.
  unset puts any setting but a trust one back to its default, or to not set.

  --limit N              history: how many changes, newest first (default: 50)

18prem sources

Registered folders, their settings, their runs, and the chunkers they may name.

shell18
prem sources add <name> <folder> [--prefix p] [--okf-bundle] [--undeclared-as-machine] [--chunker name]
prem sources set <name> [--okf-bundle on|off] [--undeclared-as-machine on|off] [--chunker name]
                        [--owner <sign-in-name>] [--hosted yes|no]
prem sources remove <name>
prem sources list
prem sources status <name>
prem sources chunkers
prem sources hosted-release --prefix p

  Registered folders, the settings each is read with, its runs, and the chunkers a source may
  name. Ingest one with prem ingest --source <name>; a change to how a source is read takes effect
  at its next ingest. Who may read its documents is the folder rule, not the source.

  --prefix p             add: the path its documents are indexed under (default: none)
  --okf-bundle           add: read it as an Open Knowledge Format bundle; set: on or off
  --undeclared-as-machine  add: in a bundle, a concept that does not say who wrote it is machine
                         written and unverified; set: on or off
  --chunker name         add, set: how its documents are cut into chunks (default: markdown)
  --owner name           set: the user who owns it and is reminded of its stale and unreviewed
                         documents; "" leaves it with no owner
  --hosted yes|no        set: whether its documents may be served to agents on a hosted model
                         (default: yes)
  --prefix p             hosted-release: the folder of a hold whose source was removed. Removing a
                         source keeps its documents indexed and its folder held; this lets them go

19prem extensions

What this deployment loads from its extensions folder, and what it allows.

shell19
prem extensions list
prem extensions allow <folder>
prem extensions disallow <name>

  list says what this process loaded from the extensions folder, the commands and settings each
  loaded one adds, what it refused and why, and what is allowed. allow measures the extension in
  that folder, the hash of its assembly and of every file its manifest lists, checks them, and
  allows it by those hashes. disallow stops allowing every hash under that name. An extension is
  used, or stops being used, when a PremAgentic process next starts.

20prem profile

A folder of plain files carrying a whole configuration.

shell20
prem profile validate <folder> [--golden-set-dir dir]
prem profile apply <folder> [--golden-set-dir dir]
prem profile show [<folder>] [--golden-set-dir dir]

  A profile is a folder of plain files carrying a whole configuration. validate checks it against
  this deployment and changes nothing; apply applies all of it or refuses all of it; show says what
  is applied, and how this deployment differs from a profile.

  --golden-set-dir dir   where a profile's golden set is copied; the server has to be able to read
                         it (default: Premagentic-golden-sets in the shared application data,
                         C:\ProgramData on Windows, beside setup's credentials folder, never in it)

21prem reminders

What each source owner is reminded of.

shell21
prem reminders run [--plan]

  Finds the documents past their stale date and the documents waiting in the review queue, groups
  them by the owner of the source each came from, and hands each owner's summary to every reminder
  sink. Documents whose source has no owner go to the administrators' summary as unowned. The
  built-in sink keeps the latest run in the database for the portal and calls nothing outside it;
  an extension can add another. Meant to run on a schedule, from Task Scheduler or cron. Exits 1
  when a sink could not take the run.

  --plan                 print what would be delivered, per owner, and deliver and write nothing

22Commands an extension adds

shell22
An extension can add commands and settings. prem extensions list names
what the loaded ones add, and prem <command> --help prints one of them
once a database is configured, since that is where the extensions
allowed to load are kept.

23Environment

shell23
Environment:
  PREM_CREDENTIALS_FILE    the app.credentials file prem setup wrote; how an installed deployment connects
  PREM_CONNECTION_STRING   a PostgreSQL connection string instead; set one of these two, not both
  PREM_DEV_DATABASE=1      the local development database in docker-compose.yml, when neither is set
                             With none of the three, every command but setup, remove, --help and
                             --version refuses to start.
  PREM_EMBEDDING_PROVIDER  local | openai | hash, or one an extension registered (default: local, fully offline)
  PREM_ONNX_MODEL_DIR      (default: models/minilm under the current folder, then beside the
                             program and each folder above it)
  PREM_EXTENSIONS_DIR      the folder whose subfolders hold extensions, when the setting
                             extensions.folder does not say. Neither one means no extensions.
  PREM_TENANT_KEY          (default: default)
  PREM_TENANT_NAME         the deployment's name, used when its tenant is first made
                             (default: Premagentic deployment)
  PREM_HEADING_PREFIX      0 disables the "title > heading" embedding context prefix (default on)