CLI reference
perpetual is Perpetual's command-line tool. It works with the same
resources as the web app and the API, and it can
manage a space's content as YAML files in
a directory you keep in git.
Install
The CLI needs Node.js 22.13 or later. Install it from npm:
npm install -g @perpetualsystems/cli
Then sign in. Pass the URL you use for the web app as the endpoint, such as
https://us.perpetualsystems.com. A browser window opens to finish signing in.
perpetual login --endpoint https://us.perpetualsystems.com
Run perpetual whoami to confirm which user and organization you are signed in
as.
Commands
A command that writes content stages its writes into a
changeset. A few commands write live
instead, such as the credential commands, because the API cannot stage what
they change. Each command's "Changes" line says which kind of write it makes.
The CLI has 146 commands.
| Area | Pages |
|---|---|
| Top-level commands | Top-level commands |
| Changesets | changeset |
| Datasets | catalog, connector, dataset, table, union, view |
| Content | dashboard, detection, folder, http-tool, integration, lookup, mapper, mcp, parser, skill, webhook |
| Content packs | pack |
| Queries | query |
| Cases and threat intelligence | case, content-work-item, threat-report |
| Accounts and access | credential, oauth-client, org, profile, user |
| Agent tooling | robot-docs |
Global flags work on every command. Exit codes and errors lists what a command returns when it fails.
GitOps files
Each file in a GitOps directory describes one resource. The suffix in its name sets the resource type.
The CLI tells a file's kind from its name.
| Area | File | Resource |
|---|---|---|
| Datasets | *.connector.yaml | Connector |
| Datasets | *.table.yaml | Table |
| Datasets | *.union.yaml | Union |
| Datasets | *.view.yaml | View |
| Content | *.dashboard.yaml | Dashboard |
| Content | *.detection.yaml | Detection |
| Content | *.folder.yaml | Folder |
| Content | *.http-tool.yaml | HttpToolConfig |
| Content | *.integration.yaml | Integration |
| Content | *.lookup.yaml | Lookup |
| Content | *.mcp.yaml | McpConfig |
| Content | *.skill.yaml | Skill |
| Content | *.webhook.yaml | WebhookConfig |
| Integration parsers and mappers | *.parser.yaml | Parser |
| Integration parsers and mappers | *.mapper.yaml | Mapper |
| Content packs | *.pack-installation.yaml | ContentPackInstallation |
| Content packs | *.detection-override.yaml | Detection |
| Content packs | *.lookup-override.yaml | Lookup |
| Content packs | *.mapper-override.yaml | Mapper |
| Content packs | *.parser-override.yaml | Parser |
| Content packs | pack.yaml | A pack's own manifest |
Configuration
- Environment variables sign a command in and pick its organization and space without flags.
- .perpetual.toml pins the endpoint, organization and space for every command run inside a repository.
Related
- MCP access, the surface outside agents use.
- Changesets, where a command's content writes land.
Perpetual CLI 0.5.0