Top-level commands
The commands that sit directly under perpetual, outside any namespace.
perpetual api
Send a raw request to the Perpetual API.
perpetual api [path] [body] [flags]
Changes: The CLI cannot require a changeset for it, because it sends whatever API request it is given.
Output: Prints raw output.
Arguments
| Argument | Required | Description |
|---|---|---|
path | Optional | [METHOD] </api/vN/path[?query]> — {orgId} becomes the chosen org. |
body | Optional | Request body: JSON, @file or @- for stdin. |
Flags
| Flag | Type | Required | Description |
|---|---|---|---|
--method, -X | string | Optional | HTTP method (default GET, or POST when a body or field is given). |
--raw-field, -f | string | Optional | String field key=value (repeatable). |
--field, -F | string | Optional | Typed field key=value: JSON-syntax number, true/false, null, @file or @- (repeatable). |
--data, -d | string | Optional | Raw body: JSON, @file or @- for stdin. |
--input | string | Optional | Raw body from a file, or - for stdin. |
--header, -H | string | Optional | Extra header 'Name: value' (repeatable); Authorization or Cookie replaces the login's credentials. |
--paginate | boolean | Optional | Follow $top/$skip to count and concatenate items. |
--include, -i | boolean | Optional | Print response headers to stderr. |
--quiet, -q | boolean | Optional | Print no status line. |
--spec | boolean | Optional | Print the vendored API spec as NDJSON and exit. |
Also accepts the global flags, including the sign-in flags.
perpetual apply
Apply exactly these GitOps files: stage them into a new changeset in dependency order, show the diff, confirm, and commit.
perpetual apply [paths] [flags]
Changes: Stages its writes into a changeset.
Output: With --json, prints its result in the JSON envelope and any error in the error envelope.
Arguments
| Argument | Required | Description |
|---|---|---|
paths | Optional | Files, directories or quoted globs. |
Flags
| Flag | Type | Required | Description |
|---|---|---|---|
--dir | string | Optional | GitOps root (default .). |
--prune | boolean | Optional | Also delete resources with a gitops: originKey in the selected files' spaces that no file in the root declares. |
--force | boolean | Optional | Skip the commit prompt (required without a terminal). |
--keep-on-failure | boolean | Optional | Keep the changeset as a draft when staging or the commit fails, to inspect it; a declined commit still deletes it. |
--name | string | Optional | Name the changeset (must not be empty); Simba may rename it if the name stops describing its changes. |
--description | string | Optional | Describe the changeset (must not be empty). |
Also accepts the global flags, including the sign-in flags.
perpetual capabilities
Describe the CLI contract for agents.
perpetual capabilities
Changes: Stages nothing.
Output: With --json, prints its result in the JSON envelope and any error in the error envelope.
Also accepts the global flags.
perpetual check
Check GitOps files offline, with no login: schemas, references and plain-text secrets. Every file under the root must load; paths narrow the other checks.
perpetual check [paths] [flags]
Changes: Stages nothing.
Output: With --json, prints its result in the JSON envelope and any error in the error envelope.
Arguments
| Argument | Required | Description |
|---|---|---|
paths | Optional | Files, directories or quoted globs (default: the whole root). |
Flags
| Flag | Type | Required | Description |
|---|---|---|---|
--dir | string | Optional | GitOps root (default .). |
Also accepts the global flags.
perpetual completion
Print a shell completion script for bash, zsh or fish.
perpetual completion <shell>
Changes: Stages nothing.
Output: Prints raw output.
Arguments
| Argument | Required | Description |
|---|---|---|
shell | Required | Shell to complete: bash, zsh, fish. One of bash, zsh, fish. |
Also accepts the global flags.
perpetual copy
Copy GitOps files into another space, with new identities and rewritten references.
perpetual copy [flags]
Changes: Stages nothing.
Output: With --json, prints its result in the JSON envelope and any error in the error envelope.
Flags
| Flag | Type | Required | Description |
|---|---|---|---|
--to-space | string | Optional | Space to copy into (SPC_*). |
--with-deps | boolean | Optional | Also copy the files the selection depends on, within its space. |
--undeployed | boolean | Optional | Set deploy: false on every copy whose kind has it. |
--out | string | Optional | Directory for the copies (default spaces/<target>/from-<source>). |
--dir | string | Optional | GitOps root (default .). |
Also accepts the global flags.
perpetual delete
Delete a resource: commit the deletion in one run after confirming, or stage it into --changeset.
perpetual delete <kind> <id> [flags]
Changes: Stages its writes into a changeset.
Output: With --json, prints its result in the JSON envelope and any error in the error envelope.
Arguments
| Argument | Required | Description |
|---|---|---|
kind | Required | Resource kind: connector, dashboard, detection, folder, http-tool, integration, lookup, mapper, mcp, parser, skill, table, union, view, webhook. |
id | Required | Resource ID. |
Flags
| Flag | Type | Required | Description |
|---|---|---|---|
--base-version | string | Optional | Expected current version for optimistic concurrency. |
--changeset | string | Optional | Stage into this draft changeset (CHG_*) instead of committing in one run. |
--force | boolean | Optional | Skip the commit prompt when committing in one run (required without a terminal). |
--name | string | Optional | Name the changeset (with --changeset, renames it; must not be empty); Simba may rename it if the name stops describing its changes. |
--description | string | Optional | Describe the changeset (with --changeset, replaces its description; must not be empty). |
Also accepts the global flags, including the sign-in flags.
perpetual login
Log in to a profile, creating it if needed, and make it the active profile.
perpetual login [flags]
Changes: Stages nothing.
Output: With --json, prints its result in the JSON envelope and any error in the error envelope.
Flags
| Flag | Type | Required | Description |
|---|---|---|---|
--profile | string | Optional | Profile to log in to (or PERPETUAL_PROFILE). The flag also makes it the active profile. |
--endpoint | string | Optional | API endpoint for a new profile. An existing profile keeps the endpoint it was created with. |
--auth | string | Optional | Authentication mode: "interactive" (default), "password", or "client-credentials" (or set PERPETUAL_AUTH). |
--email | string | Optional | User email address (or set PERPETUAL_EMAIL env var). |
--password | string | Optional | User password (DEPRECATED: visible in ps/history. Use --password-file or --password-stdin). |
--password-file | string | Optional | Read password from a file (first line). |
--password-stdin | boolean | Optional | Read password from stdin. |
--client-id | string | Optional | OAuth client ID (or set PERPETUAL_CLIENT_ID env var). Optional for interactive auth with auto-registration. |
--client-secret | string | Optional | OAuth client secret (or set PERPETUAL_CLIENT_SECRET env var). |
--redirect-uri | string | Optional | OAuth redirect URI (or set PERPETUAL_REDIRECT_URI env var). |
Also accepts the global flags.
perpetual logout
Log out of a profile, or every profile with --all, and delete its stored credentials.
perpetual logout [flags]
Changes: Stages nothing.
Output: With --json, prints its result in the JSON envelope and any error in the error envelope.
Flags
| Flag | Type | Required | Description |
|---|---|---|---|
--profile | string | Optional | Profile to log out of (or PERPETUAL_PROFILE). Without it, a terminal asks; otherwise the active profile. |
--all | boolean | Optional | Log out of every profile. |
Also accepts the global flags.
perpetual plan
Show what apply would change for these GitOps files, field by field, without changing anything.
perpetual plan [paths] [flags]
Changes: Leaves no lasting change. Without --server it only reads. With --server it stages into a temporary changeset it always deletes, and never commits.
Output: With --json, prints its result in the JSON envelope and any error in the error envelope.
Arguments
| Argument | Required | Description |
|---|---|---|
paths | Optional | Files, directories or quoted globs. |
Flags
| Flag | Type | Required | Description |
|---|---|---|---|
--dir | string | Optional | GitOps root (default .). |
--server | boolean | Optional | Ask Simba for the exact diff by staging into a temporary changeset that is always deleted. |
--prune | boolean | Optional | Also delete resources with a gitops: originKey in the selected files' spaces that no file in the root declares. |
--validate | boolean | Optional | With --server, also ask Simba to validate the staged changes and fail on any it refuses. |
--detailed-exitcode | boolean | Optional | Exit 2 when anything would change and 0 when nothing would; a usage error exits 1. |
Also accepts the global flags, including the sign-in flags.
perpetual pull
Write server resources as GitOps files.
perpetual pull [target] [flags]
Changes: Stages nothing.
Output: With --json, prints its result in the JSON envelope and any error in the error envelope.
Arguments
| Argument | Required | Description |
|---|---|---|
target | Optional | A kind (connector, dashboard, detection, folder, http-tool, integration, lookup, mapper, mcp, parser, skill, table, union, view, webhook), a resource id, or a content pack installation id (PKI_*). |
Flags
| Flag | Type | Required | Description |
|---|---|---|---|
--all | boolean | Optional | Pull every resource, with content pack installation and override files, in every space. |
--space | string, repeatable | Optional | Only these spaces: SPC_* ids, comma-separated or repeated. |
--all-overrides | boolean | Optional | Write an override file for every installed detection, lookup, parser and mapper, with every runtime field; with --all, --space or PKI_* only. |
--dir | string | Optional | GitOps root to write into (default .). |
Also accepts the global flags, including the sign-in flags.
perpetual search
Search across resources in the organization by name.
perpetual search <query> [flags]
Changes: Stages nothing.
Output: With --json, prints its result in the JSON envelope and any error in the error envelope.
Arguments
| Argument | Required | Description |
|---|---|---|
query | Required | Search text (matched against resource names). |
Flags
| Flag | Type | Required | Description |
|---|---|---|---|
--limit | string | Optional | Max results to return (1-50; the server default applies if omitted). |
--kind | string | Optional | Filter results by resource kind, CLI-side — applied AFTER the server-side --limit, so combining with --limit can return fewer of a kind than exist (raise --limit, max 50). Kinds: Case, Connector, Dashboard, Detection, Folder, Integration, Table, ThreatReport, Union, View. |
Also accepts the global flags, including the sign-in flags.
perpetual update
Update perpetual with the release installer or the package manager that installed it.
perpetual update [flags]
Changes: Stages nothing.
Output: Prints raw output.
Flags
| Flag | Type | Required | Description |
|---|---|---|---|
--version | string | Optional | Release to install, e.g. v0.5.0 (default: latest). |
--dry-run | boolean | Optional | Print what would run without changing anything. |
Also accepts the global flags.
perpetual whoami
Show who you are logged in as, and where the profile, org and login came from.
perpetual whoami
Changes: Stages nothing.
Output: With --json, prints its result in the JSON envelope and any error in the error envelope.
Also accepts the global flags, including the sign-in flags.
Perpetual CLI 0.5.0