Skip to main content

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​

ArgumentRequiredDescription
pathOptional[METHOD] </api/vN/path[?query]> — {orgId} becomes the chosen org.
bodyOptionalRequest body: JSON, @file or @- for stdin.

Flags​

FlagTypeRequiredDescription
--method, -XstringOptionalHTTP method (default GET, or POST when a body or field is given).
--raw-field, -fstringOptionalString field key=value (repeatable).
--field, -FstringOptionalTyped field key=value: JSON-syntax number, true/false, null, @file or @- (repeatable).
--data, -dstringOptionalRaw body: JSON, @file or @- for stdin.
--inputstringOptionalRaw body from a file, or - for stdin.
--header, -HstringOptionalExtra header 'Name: value' (repeatable); Authorization or Cookie replaces the login's credentials.
--paginatebooleanOptionalFollow $top/$skip to count and concatenate items.
--include, -ibooleanOptionalPrint response headers to stderr.
--quiet, -qbooleanOptionalPrint no status line.
--specbooleanOptionalPrint 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​

ArgumentRequiredDescription
pathsOptionalFiles, directories or quoted globs.

Flags​

FlagTypeRequiredDescription
--dirstringOptionalGitOps root (default .).
--prunebooleanOptionalAlso delete resources with a gitops: originKey in the selected files' spaces that no file in the root declares.
--forcebooleanOptionalSkip the commit prompt (required without a terminal).
--keep-on-failurebooleanOptionalKeep the changeset as a draft when staging or the commit fails, to inspect it; a declined commit still deletes it.
--namestringOptionalName the changeset (must not be empty); Simba may rename it if the name stops describing its changes.
--descriptionstringOptionalDescribe 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​

ArgumentRequiredDescription
pathsOptionalFiles, directories or quoted globs (default: the whole root).

Flags​

FlagTypeRequiredDescription
--dirstringOptionalGitOps 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​

ArgumentRequiredDescription
shellRequiredShell 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​

FlagTypeRequiredDescription
--to-spacestringOptionalSpace to copy into (SPC_*).
--with-depsbooleanOptionalAlso copy the files the selection depends on, within its space.
--undeployedbooleanOptionalSet deploy: false on every copy whose kind has it.
--outstringOptionalDirectory for the copies (default spaces/<target>/from-<source>).
--dirstringOptionalGitOps 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​

ArgumentRequiredDescription
kindRequiredResource kind: connector, dashboard, detection, folder, http-tool, integration, lookup, mapper, mcp, parser, skill, table, union, view, webhook.
idRequiredResource ID.

Flags​

FlagTypeRequiredDescription
--base-versionstringOptionalExpected current version for optimistic concurrency.
--changesetstringOptionalStage into this draft changeset (CHG_*) instead of committing in one run.
--forcebooleanOptionalSkip the commit prompt when committing in one run (required without a terminal).
--namestringOptionalName the changeset (with --changeset, renames it; must not be empty); Simba may rename it if the name stops describing its changes.
--descriptionstringOptionalDescribe 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​

FlagTypeRequiredDescription
--profilestringOptionalProfile to log in to (or PERPETUAL_PROFILE). The flag also makes it the active profile.
--endpointstringOptionalAPI endpoint for a new profile. An existing profile keeps the endpoint it was created with.
--authstringOptionalAuthentication mode: "interactive" (default), "password", or "client-credentials" (or set PERPETUAL_AUTH).
--emailstringOptionalUser email address (or set PERPETUAL_EMAIL env var).
--passwordstringOptionalUser password (DEPRECATED: visible in ps/history. Use --password-file or --password-stdin).
--password-filestringOptionalRead password from a file (first line).
--password-stdinbooleanOptionalRead password from stdin.
--client-idstringOptionalOAuth client ID (or set PERPETUAL_CLIENT_ID env var). Optional for interactive auth with auto-registration.
--client-secretstringOptionalOAuth client secret (or set PERPETUAL_CLIENT_SECRET env var).
--redirect-uristringOptionalOAuth 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​

FlagTypeRequiredDescription
--profilestringOptionalProfile to log out of (or PERPETUAL_PROFILE). Without it, a terminal asks; otherwise the active profile.
--allbooleanOptionalLog 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​

ArgumentRequiredDescription
pathsOptionalFiles, directories or quoted globs.

Flags​

FlagTypeRequiredDescription
--dirstringOptionalGitOps root (default .).
--serverbooleanOptionalAsk Simba for the exact diff by staging into a temporary changeset that is always deleted.
--prunebooleanOptionalAlso delete resources with a gitops: originKey in the selected files' spaces that no file in the root declares.
--validatebooleanOptionalWith --server, also ask Simba to validate the staged changes and fail on any it refuses.
--detailed-exitcodebooleanOptionalExit 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​

ArgumentRequiredDescription
targetOptionalA 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​

FlagTypeRequiredDescription
--allbooleanOptionalPull every resource, with content pack installation and override files, in every space.
--spacestring, repeatableOptionalOnly these spaces: SPC_* ids, comma-separated or repeated.
--all-overridesbooleanOptionalWrite an override file for every installed detection, lookup, parser and mapper, with every runtime field; with --all, --space or PKI_* only.
--dirstringOptionalGitOps root to write into (default .).

Also accepts the global flags, including the sign-in flags.

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​

ArgumentRequiredDescription
queryRequiredSearch text (matched against resource names).

Flags​

FlagTypeRequiredDescription
--limitstringOptionalMax results to return (1-50; the server default applies if omitted).
--kindstringOptionalFilter 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​

FlagTypeRequiredDescription
--versionstringOptionalRelease to install, e.g. v0.5.0 (default: latest).
--dry-runbooleanOptionalPrint 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