Skip to main content

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.

AreaPages
Top-level commandsTop-level commands
Changesetschangeset
Datasetscatalog, connector, dataset, table, union, view
Contentdashboard, detection, folder, http-tool, integration, lookup, mapper, mcp, parser, skill, webhook
Content packspack
Queriesquery
Cases and threat intelligencecase, content-work-item, threat-report
Accounts and accesscredential, oauth-client, org, profile, user
Agent toolingrobot-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.

AreaFileResource
Datasets*.connector.yamlConnector
Datasets*.table.yamlTable
Datasets*.union.yamlUnion
Datasets*.view.yamlView
Content*.dashboard.yamlDashboard
Content*.detection.yamlDetection
Content*.folder.yamlFolder
Content*.http-tool.yamlHttpToolConfig
Content*.integration.yamlIntegration
Content*.lookup.yamlLookup
Content*.mcp.yamlMcpConfig
Content*.skill.yamlSkill
Content*.webhook.yamlWebhookConfig
Integration parsers and mappers*.parser.yamlParser
Integration parsers and mappers*.mapper.yamlMapper
Content packs*.pack-installation.yamlContentPackInstallation
Content packs*.detection-override.yamlDetection
Content packs*.lookup-override.yamlLookup
Content packs*.mapper-override.yamlMapper
Content packs*.parser-override.yamlParser
Content packspack.yamlA 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.

Perpetual CLI 0.5.0