> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parmanasystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recipes

> Practical ways to use the parmana command: reviewing a change with a dry run, scripting with JSON output, and running the approval flow in CI.

These recipes show the common ways to use the command in practice. Each one uses only the options described in the [command reference](https://docs.parmanasystems.com/cli/reference.md).

## Review a change before anyone approves it

A reviewer can see exactly what would be sent, without a token and without sending anything:

```bash theme={null}
parmana-ops policy propose policy.json --name customer-refund --version 1.3.0 --reason "Refuse all refunds" --dry-run
```

The output shows the method, the full address and the body, with the token masked. Attach it to the review.

## Check what is pending, in a script

```bash theme={null}
parmana-ops policy status customer-refund 1.3.0 --output json
```

Read the `changes` array. An empty array means nothing is pending for that version.

## Stop a script when a refusal happens

Exit codes tell a script what kind of failure occurred:

```bash theme={null}
parmana-ops approval submit --pending "$PENDING_ID" --action approve --envelope envelope.json --output json > result.json
case $? in
  0) echo "approved" ;;
  1) echo "refused by the server; see result.json" ;;
  2) echo "usage error; fix the command" ;;
esac
```

With `--output json`, the refusal details are in `result.json`, so the script never has to parse the text.

## Wait for a slow server

```bash theme={null}
parmana-ops policy status customer-refund 1.3.0 --timeout 60
```

Reads are also retried automatically. A write is never retried, so a slow write that times out has to be checked with `policy status` before it is sent again.

## Run the approval flow in CI

Keep the checker's private key out of CI. The signing step runs on the checker's own machine. A CI job can do the parts that need no key:

```yaml theme={null}
- run: npm ci
- run: npm run build --workspace=packages/cli
- run: node packages/cli/dist/index.js log verify --require-coverage
```

`log verify` is offline. It needs no token and no database, so it is safe to run on every pull request.

## Use profiles for several environments

Put each environment's address in the config file, and choose one per command:

```bash theme={null}
parmana-ops policy status customer-refund 1.3.0 --profile local
parmana-ops policy status customer-refund 1.3.0 --profile prod
```

The token stays in `PARMANA_TOKEN`, so the same token is sent to each profile. Do not reuse a production token against a local server.

## Install shell completion

PowerShell:

```powershell theme={null}
parmana-ops completion powershell | Out-String | Invoke-Expression
```

bash:

```bash theme={null}
eval "$(parmana-ops completion bash)"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.