# Recipes {#recipes}


Concrete patterns for the three audiences the CLI is built for.


## CI pipelines {#ci-pipelines}



### GitHub Actions: draft a release campaign {#github-actions-draft-a-release-campaign}


Use `nitrosend mcp tools call` to create a reviewed campaign draft after a deploy. `--machine` gives stable JSON, exit codes, and an auto-issued idempotency key.

```yaml
name: Draft release campaign
on:
  release:
    types: [published]

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @nitrosend/cli
      - name: Draft release email
        env:
          NITROSEND_API_KEY: ${{ secrets.NITROSEND_API_KEY }}
        run: |
          nitrosend mcp tools call nitro_compose_campaign --machine --args "$(cat <<EOF
          {
            "name": "Release ${{ github.event.release.tag_name }}",
            "channel": "email",
            "subject": "Release ${{ github.event.release.tag_name }}",
            "body": "Release notes are live: ${{ github.event.release.html_url }}",
            "idempotency_key": "release-${{ github.event.release.id }}"
          }
          EOF
          )"
```

The `idempotency_key` inside `--args` is what the platform dedupes against — set it from a stable, retry-survivable value like the release ID so a re-run of the job won't create duplicate drafts. Branch on exit codes for retry strategy: `75` retriable, `77` means rotate the API key, `78` means upgrade the CLI step.


### Daily account health check {#daily-account-health-check}


Run the dashboard read, fail the job on blockers:

```bash
#!/usr/bin/env bash
set -euo pipefail

result=$(nitrosend --machine)
blockers=$(echo "$result" | jq -r '.sidecars.blockers // [] | length')

if [ "$blockers" -gt 0 ]; then
  echo "$result" | jq '.sidecars.blockers'
  exit 1
fi
```


## Local operating {#local-operating}



### Quick status snapshot {#quick-status-snapshot}


Three commands cover most "what's the state of my account" questions:

```bash
nitrosend                              # account state, blockers, next_action
nitrosend mcp resources read nitro://account
nitrosend mcp tools call nitro_get_insights --args '{"scope":"account"}'
```


### Pipe campaign results into a spreadsheet {#pipe-campaign-results-into-a-spreadsheet}


```bash
nitrosend mcp tools call nitro_query \
  --args '{"resource":"campaigns","page":1,"per_page":100}' \
  --csv > campaigns.csv
```

CSV mode is table-only — no envelope, no sidecars. Use it when you want raw rows.


### Purchase a plan or add prepaid funds {#purchase-a-plan-or-add-prepaid-funds}


The Nitrosend CLI invokes `nitro_manage_billing` over MCP directly. No
payment-specific CLI or external runtime sits between the command and
Nitrosend.

~~~bash
# Inspect account route, plan, and prepaid balance
nitrosend mcp tools call nitro_manage_billing --machine \
  --args '{"operation":"status"}'

# List plans, then prepare owner-approved checkout
nitrosend mcp tools call nitro_manage_billing --machine \
  --args '{"operation":"plans"}'
nitrosend mcp tools call nitro_manage_billing --machine \
  --args '{"operation":"checkout","params":{"plan_id":2},"idempotency_key":"plan-pro-acme-2026-08-31"}'

# Or prepare a separate prepaid funding purchase
nitrosend mcp tools call nitro_manage_billing --machine \
  --args '{"operation":"add_funds","params":{"amount_cents":5000,"currency":"USD"},"idempotency_key":"fund-validation-acme-2026-08-31"}'
~~~

The command returns an approval URL and purchase ID when provider approval is
needed. The account owner completes Checkout in a browser. Poll
`checkout_status` until the plan is `active`, or
`funding_purchase_status` until funds are `credited`.

See [Payments for agents](https://docs.nitrosend.com/guides/agent-payments.md) for complete commands, Link
and Stripe CLI terminology, and recovery rules.


### Replay a recent command {#replay-a-recent-command}


```bash
nitrosend recent              # show the last 10 commands
nitrosend redo 1 --explain    # show what `redo 1` would run, without running
```

`recent` and `redo` are local-only — they never call the API and they redact obvious secrets in their stored history.


### Tab completion {#tab-completion}


```bash
# bash
nitrosend completion bash >> ~/.bashrc

# zsh
nitrosend completion zsh > ~/.config/zsh/completions/_nitrosend

# fish
nitrosend completion fish > ~/.config/fish/completions/nitrosend.fish
```


## Agent runners {#agent-runners}



### Plan, then act {#plan-then-act}


Use `--explain` to get a deterministic plan before deciding to execute. The plan is the same envelope shape as a real run, with `would_execute: false`.

```bash
plan=$(nitrosend mcp tools call nitro_compose_campaign \
  --args "$(cat brief.json)" --explain --machine)

# Inspect the plan, decide, then run for real
echo "$plan" | jq '.data'

if [ "$(echo "$plan" | jq -r '.data.would_execute')" = "false" ]; then
  nitrosend mcp tools call nitro_compose_campaign \
    --args "$(cat brief.json)" --machine
fi
```


### Discover the contract before calling {#discover-the-contract-before-calling}


Cache the descriptor at startup. Don't guess flags.

```bash
nitrosend describe mcp tools call --json | jq '.input_schema'
```

The descriptor includes safety class, dry-run support, idempotency policy, and an `agent.suitable` flag. Skip any command marked `suitable: false` from an autonomous runner.


### Approval handoff {#approval-handoff}


When an agent needs human sign-off mid-run, hand off to `approve` / `reject` and pause. The CLI exposes these as stable stubs today and will gain an SSE waiter endpoint in a future release.

```bash
# Agent emits a token, then waits.
nitrosend approve $TOKEN   # human runs this
nitrosend reject  $TOKEN   # or this
```


### Read sidecars for next-action loops {#read-sidecars-for-next-action-loops}


Don't write your own "what should I do next" logic. The platform already returns one. Read `sidecars.next_action` and `sidecars.suggested_tool_calls` and let it drive the loop.

```bash
result=$(nitrosend mcp tools call nitro_get_status --machine)
next=$(echo "$result" | jq -r '.sidecars.next_action // empty')
[ -n "$next" ] && echo "Next: $next"
```


## See also {#see-also}


- [Agent mode](https://docs.nitrosend.com/cli/agent-mode.md) — the full machine-readable contract
- [Project config](https://docs.nitrosend.com/cli/project-config.md) — environments and the production guard
- [MCP integrations overview](https://docs.nitrosend.com/integrations/overview.md) — when to use a chat MCP client instead
