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
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
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.
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.
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.
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.
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.
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
08prem search
Searches as one caller.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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
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)