Author policies with the CLI

The para keys permissions commands check a Guardrail or Request policy written as JSON against your API key and move it from draft to active to retired. The same commands run in a terminal or in a CI job.

You author and test policies on your beta API key. The CLI cannot change production policies: once a policy works on beta, you ask Para to review it and apply it to your production key.

Before you start

Every command acts on one API key in your selected organization and project, so set that context first.

Install the CLI and sign in

Install the CLI, then sign in with your developer account.

para login

Select the organization and project

para orgs switch
para projects switch

Find your beta key

para keys list --environment beta

Copy the key’s ID. The examples on this page call it KEY_ID. The Developer Portal shows this key as the Development key. If the project has a single beta key, you can leave KEY_ID out.

The CLI uses beta keys unless you changed its default. If PARA_ENVIRONMENT, a .pararc file, or defaultEnvironment selects prod, add --environment beta to the commands on this page.

Inspect the key

Read what the key already has before you change it. state returns every policy record on the key, and catalog returns the policy language the key accepts.

para keys permissions state KEY_ID --json
para keys permissions catalog KEY_ID --json

Without --json, state prints a summary: the state name, whether Permissions is enabled, and how many policies are active and in draft. The JSON lists every record in policies, plus activePolicies (active records whose time window is open now) and draftPolicies. Each record has these fields:

Field	Meaning
`recordId`	One saved version of a policy, such as `policy-record:...`. `replace`, `activate`, `deactivate`, and `archive` take this ID.
`policyId`, `policyVersion`	The `id` and `version` from your JSON. One policy ID collects several records over time.
`lifecycle`	Where the record stands, from the table below.
`activation`	The record’s time window: `effectiveFrom` and, when set, `effectiveUntil`.

Lifecycle	Enforced	How a record gets there
`draft`	No	`create`, or `replace` on a draft
`active`	Inside its time window	`activate` on a draft, or `replace` on an active record
`inactive`	No	`deactivate`
`superseded`	No	A newer version of the same policy became active
`archived`	No	`archive`, or `replace` on a draft

catalog returns the condition kinds, effects, selector scopes, and facts the key accepts, with the operators each fact allows. Without --json, it prints only the catalog versions and the number of facts.

Write the policy

A policy file holds one JSON object. metadata.productMode sets its kind: "guardrail" for app-owned wallets, or "delegation" for a Request on user-owned wallets. Write amounts as strings in the chain’s base units, such as wei or lamports, and use integer strings for version, starting at "1", because replace expects the next integer.

Guardrail
Request

This Guardrail limits SOL transfers from the app-owned Solana wallets on the key. It blocks any transfer above 2 SOL, and any transfer that would take a wallet past 10 SOL in one UTC day.

guardrail.json

{
  "id": "solana-sol-limits",
  "schemaVersion": "permissions.policy.v1",
  "version": "1",
  "selector": {
    "walletType": "SOLANA",
    "chainId": "solana:mainnet"
  },
  "rules": [
    {
      "id": "block-large-transfer",
      "effect": "deny",
      "actions": ["transfer_native"],
      "when": {
        "kind": "compare",
        "fact": "request.value.baseUnits",
        "op": "gt",
        "value": "2000000000"
      }
    },
    {
      "id": "block-over-daily-limit",
      "effect": "deny",
      "actions": ["transfer_native"],
      "when": {
        "kind": "aggregate",
        "fact": "wallet.spend.native",
        "op": "gt",
        "value": "10000000000",
        "window": "1d"
      }
    }
  ],
  "metadata": {
    "productMode": "guardrail",
    "description": "Limit SOL transfers to 2 SOL each and 10 SOL per day"
  }
}

A Guardrail rule can deny or require_approval. Without a walletId in the selector, the policy covers every app-owned Solana wallet on the key.Para also accepts a Guardrail allow whose only action is raw_signature, but a Guardrail never needs it: app-owned wallets already sign raw signatures by default. Raw signatures carry no network a selector can name, so a policy that sets chainId, like this one, never matches them. To deny raw signatures or require approval for them, write a Guardrail without chainId.

This Request asks users for standing access to send small amounts of ETH on Base: up to 0.05 ETH per transfer and 0.2 ETH per UTC day. It applies to a user’s EVM wallet once that user consents.

request.json

{
  "id": "base-eth-allowance",
  "schemaVersion": "permissions.policy.v1",
  "version": "1",
  "selector": {
    "walletType": "EVM",
    "chainId": "8453"
  },
  "rules": [
    {
      "id": "small-eth-transfers",
      "effect": "allow",
      "actions": ["transfer_native"],
      "when": {
        "kind": "all",
        "of": [
          {
            "kind": "compare",
            "fact": "request.value.baseUnits",
            "op": "lte",
            "value": "50000000000000000"
          },
          {
            "kind": "aggregate",
            "fact": "wallet.spend.native",
            "op": "lte",
            "value": "200000000000000000",
            "window": "1d"
          }
        ]
      }
    }
  ],
  "metadata": {
    "productMode": "delegation",
    "description": "Send up to 0.05 ETH per transfer and 0.2 ETH per day on Base"
  }
}

A Request rule can allow, or require_approval with an approvalRequirement. It cannot deny. Users see metadata.description as the title of the permission on the consent screen.

Validate, create, and activate

A new policy goes through three commands. It affects signing only after the last one.

Validate

para keys permissions validate KEY_ID --file guardrail.json

validate checks the policy against the key without saving anything. It covers the schema, the rules allowed for the policy’s kind, the facts and actions available for its wallet type, and any wallets or users the selector names. An invalid policy prints each error with its JSON path and exits with code 10. A valid policy prints a warning for each active policy of the same kind whose selector overlaps it, because both policies can apply to the same requests.Two policy features must be enabled for the key before you use them: approval requirements (approvalRequirement on a rule) and adjustable parameters. If the policy uses one that is not enabled, validation fails with permissions_v2_extension_unavailable. Contact Para to enable it.

Create a draft

para keys permissions create KEY_ID --file guardrail.json

create validates the file again, saves it as a draft, and prints the new recordId with the activate command to run next. A draft does not affect signing. The key holds one Guardrail draft and one Request draft at a time, so activate or archive a draft before you create another of the same kind.

Activate

para keys permissions activate RECORD_ID KEY_ID
para keys permissions state KEY_ID

activate asks for confirmation, makes the draft active, and turns on Permissions for the key. It works only while the draft’s time window is open. If another version of the same policy id is active, that version becomes superseded. Activation can also invalidate open approval cases. Read state to confirm the result.

If the key still uses a policy from Para’s earlier permissions system, the first activation replaces it. That earlier policy does not come back if you later deactivate every policy.

Test on beta

A valid policy can still miss your intent. On beta, send at least one request that each rule should stop and one it should let through, using the same wallets and flows as your app. Exercise a Guardrail by signing from an app-owned wallet on your backend, and a Request by having a test user grant consent in your app first. Each platform’s guide covers the details: REST API, Node & Server, React & Web, and React Native.

Update a policy

replace publishes the next version of a policy from an edited file. Use it to change rules, conditions, or the time window of a draft or active policy.

para keys permissions replace RECORD_ID KEY_ID --file guardrail.json

The edited file keeps the id, selector, and metadata.productMode of the record it replaces, and sets version to one more than the highest version of that policy, for example "2" after "1". To cover different wallets or networks, create a separate policy instead. Without --effective-from or --effective-until, the new version keeps the current time window.

Replacing	Result
An active record	The new version is active immediately and the old record becomes `superseded`. Both the current and the new time window must be open.
A draft	The new version is saved as a draft and the old draft is archived.

To stage a change instead, create the next version as a draft and activate it when you are ready. Activation supersedes the active version with the same id. Replacing an active policy can invalidate open approval cases.

Users consent to one exact version of a Request. When you replace an active Request, each user has to consent again before the new version’s rules apply to them.

Deactivate and archive

Deactivate a policy to stop enforcing it, and archive records you no longer need. The Developer Portal calls these actions turning a permission off and deleting it.

para keys permissions deactivate RECORD_ID KEY_ID
para keys permissions archive RECORD_ID KEY_ID

deactivate moves an active record to inactive. An inactive record cannot be activated again, so to restore the policy, create it with the next version, activate that draft, and archive the old record. archive retires a draft, inactive, or superseded record; deactivate an active record before you archive it. Both commands ask for confirmation unless you pass --yes. deactivate can also invalidate open approval cases.

Permissions enforces policies for a key only while at least one active policy is inside its time window. When the last one is turned off or its window ends, Para stops checking policies on REST and SDK signing. App-owned wallets then sign without checks. User-owned wallets show the same review pop-ups as a key without Permissions, such as those the Transaction Pop-ups setting turns on.

Open approval cases

When a rule requires approval, the signing request opens an approval case and waits for reviewers. An approval case is open while it is pending, and after it completes until it is used to sign or expires. Para refuses a change that would invalidate open cases until you confirm it. A confirmed change ends those cases as invalidated, and their requests need a new attempt. In the CLI, replace, activate, and deactivate run this check:

How you run the command	When the change would invalidate open cases
In a terminal, without `--yes`	The CLI says how many cases the change would invalidate and asks whether to apply it anyway. Answer yes to apply the change and invalidate them, or no to leave everything as it was.
With `--yes`	Nothing changes. The command prints the error message, which gives the number of cases, and exits with code `10`. With `--json`, the error also has `errorCode` `PERMISSIONS_V2_APPROVAL_CASES_AFFECTED` and the case IDs in `details.affectedCaseIds`.
With `--force`	The command applies the change and invalidates the cases without asking about them.

With --yes --json, the error looks like this:

{
  "error": {
    "type": "PermissionsV2ApprovalCasesAffectedError",
    "errorCode": "PERMISSIONS_V2_APPROVAL_CASES_AFFECTED",
    "exitCode": 10,
    "message": "This change would invalidate 2 open approval cases. Pass --force to apply it and invalidate them.",
    "details": {
      "affectedCaseIds": ["ca_7d1e...", "ca_b42f..."]
    }
  }
}

Pass --force only when the requests behind those cases can be sent again under the new policies. create and archive never touch approval cases, so they have no --force flag.

Schedule with time windows

A time window limits when an active policy applies. Set it with --effective-from and --effective-until on create or replace; activate takes no window flags.

para keys permissions create KEY_ID --file request.json \
  --effective-until 2026-12-31T23:59:59Z
para keys permissions activate RECORD_ID KEY_ID

This draft’s window opens when create saves it, so you can activate it right away. The policy stops applying after 23:59:59 UTC on December 31, 2026. activate works only while the draft’s window is open. Before a later --effective-from arrives, activate exits with code 10 and reports policy_record_activation_window_inactive. To start a policy at a set time, create the draft in advance and run activate at or after its start, for example from a scheduled CI job. Until you activate or archive that draft, the key cannot hold another draft of the same kind.

Write timestamps in UTC as ISO 8601 ending in Z, with optional milliseconds, such as 2026-11-01T00:00:00.000Z. Offsets such as +01:00 are rejected.
--effective-until must be later than --effective-from. The window includes both ends.
Without --effective-from, create opens the window when it saves the draft. Without --effective-until, the window has no end.
On replace, each flag you leave out keeps the current record’s value.

An active policy past its effectiveUntil no longer applies, and the Developer Portal shows it as Expired. Because replace needs both windows open, you cannot replace an expired policy. Create the next version with a current window and activate it instead.

Run in CI and scripts

The commands run without prompts once they have everything they need. Pin the environment, organization, project, and key, pass --yes to the commands that ask for confirmation, and add --json to read results.

set -euo pipefail
export PARA_ENVIRONMENT=beta
export PARA_ORG_ID=org_123
export PARA_PROJECT_ID=proj_123
KEY_ID=key_123

para auth status
para keys permissions validate "$KEY_ID" --file guardrail.json --json
RECORD_ID=$(para keys permissions create "$KEY_ID" --file guardrail.json --json | jq -r '.policy.recordId')
para keys permissions activate "$RECORD_ID" "$KEY_ID" --yes --json

replace, activate, deactivate, and archive require --yes with --json.
--yes does not confirm changes that invalidate open approval cases. If replace, activate, or deactivate would invalidate them, the command makes no change and exits with code 10, with PERMISSIONS_V2_APPROVAL_CASES_AFFECTED in the --json output. Pass --force only in jobs that are meant to invalidate them.
Pass the key ID. With --json, the CLI cannot ask which key to use when the project has more than one beta key.
--file - reads the policy from a pipe. The CLI refuses stdin from an interactive terminal.
Every command uses the developer session that para login stores. para auth status fails early when that session is missing or expired.

Read the JSON on stdout and the exit code to decide what the job does next.

JSON output

With --json, each command writes one JSON document to stdout.

Outcome	stdout
Success	`validate` returns `{ valid, errors, policy, overlaps }`. `create`, `replace`, `activate`, `deactivate`, and `archive` return `{ policy, state }`: the record and the key’s new state.
Invalid policy from `validate`, `create`, or `replace`	`{ valid: false, errors: [{ code, path, message }] }`
Any other error	`{ "error": { type, errorCode, exitCode, message, details } }`, with the message repeated on stderr

Exit codes

Exit code	Meaning
`0`	Success.
`1`	Unexpected error (`UNKNOWN_ERROR`), such as a policy file that does not exist or a project with no API keys.
`2`	Usage error: a missing flag, `--json` without `--yes`, a write to a key that is not a beta key (`PERMISSIONS_BETA_KEY_REQUIRED`), several beta keys and no key ID, or a prompt the run cannot show.
`3`, `4`	No session, or the session expired. Run `para login`.
`5`	Para refused access (`API_FORBIDDEN`). The CLI shows a generic message for most refusals.
`6`	The key was not found (`API_NOT_FOUND`).
`7`	Para’s rate limit was reached (`API_RATE_LIMITED`).
`8`	Network error, including `PERMISSIONS_V2_WRITE_OUTCOME_UNKNOWN`.
`10`	Validation error, one of: an invalid policy; a policy file that is not one JSON object (`PERMISSIONS_V2_POLICY_JSON_INVALID`, `PERMISSIONS_V2_POLICY_JSON_OBJECT_REQUIRED`); field errors from Para in `details.errors` (`API_VALIDATION_ERROR`), such as a version conflict, a record that does not exist or is in the wrong lifecycle (`policy_record_not_found`, `policy_record_archive_active`), or a closed time window on `activate` (`policy_record_activation_window_inactive`); or open approval cases the change would invalidate, listed in `details.affectedCaseIds` (`PERMISSIONS_V2_APPROVAL_CASES_AFFECTED`).
`11`	Para server error (`API_SERVER_ERROR`) while the CLI reads or validates, including the validation that `create` and `replace` run first. A server error during a write exits with `8` and `PERMISSIONS_V2_WRITE_OUTCOME_UNKNOWN` instead.

The CLI never retries create, replace, activate, deactivate, or archive. If it cannot confirm that a change went through, it exits with PERMISSIONS_V2_WRITE_OUTCOME_UNKNOWN. Read state before you run the command again. activate, deactivate, and archive check state themselves and report success when the record already has its new lifecycle, and running create again with the same file returns the existing draft instead of saving a second one.

The Permissions errors reference lists the error codes these commands can return.

Go to production

The CLI writes only to beta keys. create, replace, activate, deactivate, and archive stop with PERMISSIONS_BETA_KEY_REQUIRED when the key is not a beta key, including with --environment prod. state, catalog, and validate work on any key, so you can read the policies on your production key from the CLI. Publishing to production goes through a review. Once your policies work on beta, request a production review from your Production key in the Developer Portal, and Para applies the reviewed policies to production. Follow Go to production for your platform: REST API, Node & Server, React & Web, or React Native.

Next steps

For every argument and flag, see the command reference.

Overview

CLI

AI Tooling

Author policies with the CLI

Before you start

Inspect the key

Write the policy

Validate, create, and activate

Test on beta

Update a policy

Deactivate and archive

Open approval cases

Schedule with time windows

Run in CI and scripts

Go to production

Next steps

​Before you start

​Inspect the key

​Write the policy

​Validate, create, and activate

​Test on beta

​Update a policy

​Deactivate and archive

​Open approval cases

​Schedule with time windows

​Run in CI and scripts

​Go to production

​Next steps

Before you start

Inspect the key

Write the policy

Validate, create, and activate

Test on beta

Update a policy

Deactivate and archive

Open approval cases

Schedule with time windows

Run in CI and scripts

Go to production

Next steps