Piping & secrets

How to feed secret values, file bodies, and stdin into the CLI safely.

Many CLI commands take content that could be:

• Sensitive (API keys, tokens, DB URLs).
• Large (multi-line prompts, markdown notes, JSON payloads).
• Coming from another process (a previous command’s output).

The CLI supports a consistent input syntax for these across every subcommand.

The three input modes

Wherever the CLI accepts a value that could be a secret, a file, or a pipe, it recognizes:

• ? — prompt interactively. Input is masked for secret fields, unmasked otherwise.
• - — read one line from stdin. Pipe-friendly.
• @<path> — read from a file. Whole-file content becomes the value.
• Any other value — used literally, with a shell-history warning for secret fields.

Examples:

# Interactive prompt
nora tools headers add t_api --name Authorization --value ?

# Pipe from previous command
echo -n "$MY_TOKEN" | nora providers set openai --stdin

# From file
nora agents update ag_1 --set-prompt-file prompts/support.md

# Literal (avoid for secrets)
nora tools headers add t_api --name Authorization --value "Bearer sk-..."

Which fields accept which mode

Most non-secret fields (names, descriptions, prompts) accept @<path> for file-based input. Secret-sensitive fields (--api-key, --auth-value, header values, DB URLs) also accept ? for masked prompt and - for stdin.

When in doubt, <command> --help shows the specific input contract for each flag.

Reading a value from another CLI

Anywhere you can pass a literal, you can pass a subshell:

nora providers set openai --stdin <<< "$(vault read -field=key secret/nora/openai)"

nora tools headers add t_api \
  --name Authorization \
  --value "Bearer $(aws secretsmanager get-secret-value --secret-id nora/api --query SecretString --output text)"

Passing multi-line content

@file for anything multi-line — prompts, note bodies, JSON payloads:

nora agents update ag_1 --set-prompt-file prompts/support-v3.md

nora memory notes upsert sp_wiki \
  --path playbooks/refunds.md \
  --body @refunds.md

Or heredoc + stdin:

cat <<'PROMPT' | nora agents update ag_1 --set-prompt -
You are a support assistant.
Answer questions about billing, refunds, and account issues.

If unsure, say so explicitly.
PROMPT

Note: not every command supports - for this specific flag — --help confirms.

Secrets and shell history

Passing a secret as a literal on the command line writes it to your shell history. Not just risky — often violates security policy.

Symptoms:

# BAD — this goes in ~/.bash_history / ~/.zsh_history
nora providers set openai sk-abc123...

Fix:

# Good — one of:
nora providers set openai --env OPENAI_API_KEY       # env var
nora providers set openai --stdin < ~/.nora/openai   # file (with 0600 perms)
echo "$OPENAI_API_KEY" | nora providers set openai --stdin
nora providers set openai --stdin                    # interactive prompt (paste)

The CLI warns when it detects a secret-shaped literal but doesn’t refuse — you can override if you have your reasons.

Piping between nora commands

Because many commands support --json, they compose:

# Delete all superseded documents (with confirmation)
nora documents list --json | \
  jq -r '.[] | select(.superseded) | .id' | \
  xargs -n1 nora documents delete

# Publish every Flow that has an unpublished draft
nora flows list --json | \
  jq -r '.[] | select(.draft_differs_from_published) | .slug' | \
  while read slug; do
    nora flows publish "$slug" --summary "batch publish $(date +%Y-%m-%d)"
  done

Reading complex structures via jq

Most --json output is arrays or objects. Common patterns:

# Get first agent block's ID
nora flows get support | jq -r '.blocks[] | select(.kind=="agent") | .id' | head -n1

# Sum trace cost
nora traces list --from 2026-07-01 --json | jq '[.[].cost_cents] | add / 100'

# Filter by nested field
nora agents sources list ag_1 --json | jq '.[] | select(.preset=="high-precision")'

Environment variables for CI

The CLI reads env vars for auth and workspace context:

env:
  NORA_TOKEN: ${{ secrets.NORA_TOKEN }}
  NORA_TENANT: ${{ vars.NORA_WORKSPACE }}
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Then commands become:

nora providers set openai --env OPENAI_API_KEY
nora flows publish support --summary "$GIT_COMMIT_MSG"

No credentials in the command line, no state written to disk.

Quoting rules

Bash and zsh handle quoting differently for special chars in shell values. If a value contains spaces, $, !, or #:

# Safe: single quotes preserve everything literally
nora agents update ag_1 --set-prompt 'You are $friendly.'

# Or use --set-prompt-file to sidestep quoting entirely
nora agents update ag_1 --set-prompt-file prompt.md

Interpolation-heavy JSON payloads: use jq -c to compact a JSON file into a single line:

nora retrieval presets upsert my-preset \
  --name "My preset" \
  --config "$(jq -c . preset.json)"

Exit codes

The CLI follows standard Unix exit codes:

• 0 — success.
• 1 — general error.
• 2 — misuse (bad flags, missing required args).
• 4 — not authenticated.
• 8 — permission denied (auth OK but role insufficient).
• 16 — server error (5xx from platform).
• 64 — command not found or malformed.

CI can gate on exit code:

if ! nora flows publish support --summary "$MSG"; then
  echo "Publish failed"
  exit 1
fi

When something’s not working

• Turn on --verbose to see the full request/response.
• Check nora auth status to confirm workspace and token.
• Confirm the pinned Flow: nora flows current.
• For CI, echo the exit code: nora flows publish support; echo "Exit: $?".