PII Redaction

The Nexudus CLI automatically redacts personally identifiable information (PII) when it detects non-interactive execution, such as when output is piped to another tool or script. This is a security feature that prevents sensitive data (names, emails, phone numbers, addresses, dates of birth) from flowing into AI agent contexts or logs.

Available since CLI v5.0.16. PII redaction is enabled by default and cannot be disabled by flags.

What is PII?

PII includes any information that can identify a real person:

Category	Examples
NAME	FullName, NickName, Salutation, company names in context
EMAIL	Email addresses, contact emails, welcome emails
PHONE	Mobile phones, landlines, fax numbers
ADDRESS	Street address, postal code, city, state, country
DOB	Date of birth
SOCIAL	Twitter, Facebook, Google, Telegram handles
FINANCIAL	Bank accounts, tax IDs, VAT numbers
ID_DOC	Passport numbers, national IDs
BIO	Free-text profiles or notes that may contain PII

When is PII redacted?

PII redaction is automatic and structural — it depends on your execution context, not on flags you can omit:

Context	Status	Reason
Interactive terminal (typing commands)	❌ OFF	You’re a human — trusted context
Piped/redirected output (e.g., `\| jq`)	✅ ON	Data may enter scripts or logs — untrusted
Non-TTY execution (no terminal attached)	✅ ON	Likely automated — assume untrusted
With unlock token (time-limited override)	❌ OFF	Human confirmed PII needed — checked & logged

How to detect redaction status

Every CLI command response includes two fields that tell you whether PII is redacted:

{
  "piiRedaction": "on",
  "piiRedactionReason": "non-interactive",
  "ok": true,
  "data": { ... }
}

Field	Values
`piiRedaction`	`"on"` = PII is redacted; `"off"` = PII is visible
`piiRedactionReason`	`"interactive terminal"`, `"non-interactive"`, or `"unlocked (expires TIMESTAMP)"`

How PII looks when redacted

When PII is redacted, sensitive fields are replaced with deterministic tokens:

«PII:EMAIL:a3f2b1c9»
«PII:NAME:7e4d2f8a»
«PII:PHONE:1b3c5d7e»
«PII:ADDR:f5e2c1b4»

Token anatomy

«PII:{CATEGORY}:{HASH}»

Part	Example	Meaning
`PII`	constant	Identifies this as a PII token
`CATEGORY`	`EMAIL`	The type of PII (EMAIL, NAME, PHONE, ADDR, DOB, etc.)
`HASH`	`a3f2b1c9`	First 8 chars of SHA256(value + per-install salt)

Why tokens?

Stable: The same real value always produces the same token. You can reference entities by token across multiple commands.
Opaque: Tokens cannot be reversed into real values. An LLM cannot derive personal data from a token.
Obvious: Tokens are visually distinct from real data — not easily confused with actual emails or names.
Resolvable: When you pass a token back to the CLI as an argument, it resolves to the real value before sending to the API.

Using tokens in commands

You can pass tokens back to the CLI as arguments — the CLI transparently resolves them to real values before sending to the API:

# List coworkers — get tokenized output
$ nexudus coworkers list --json
{
  "piiRedaction": "on",
  "data": [
    {
      "id": 123456,
      "fullName": "«PII:NAME:7e4d2f8a»",
      "email": "«PII:EMAIL:a3f2b1c9»"
    }
  ]
}

# Update that coworker using the token
$ nexudus coworkers update 123456 --email "«PII:EMAIL:a3f2b1c9»"

# The CLI resolves the token → real value before the API call
✓ Coworker 123456 updated

This is particularly useful for AI agents: they can read tokenized entity data, build command arguments using tokens, and pass them back without ever seeing real PII.

Unlocking PII (time-limited override)

If you’re a human operator and genuinely need to see full PII in a non-interactive context (e.g., piping output to jq), you can temporarily unlock PII:

nexudus config set pii-mode unlocked --ttl 30m

Unlock requirements

Must be interactive — the command shows a confirmation prompt that requires human approval. If stdin is redirected or piped, the command refuses to run.
Time-limited — defaults to 30 minutes. Maximum allowed: 8 hours.
Auditable — unlock events are logged to telemetry (the fact that an unlock occurred, plus the TTL; no PII is logged).

Example unlock workflow

# Terminal: You need to export full PII for a report
$ nexudus config set pii-mode unlocked --ttl 2h

🔓 Unlock PII for 2 hours? This will expose personal data. [y/N] y

✓ PII unlocked until 2026-05-14T13:30:00Z

# Now redaction is temporarily OFF for 2 hours
$ nexudus coworkers list --json
{
  "piiRedaction": "off",
  "piiRedactionReason": "unlocked (expires 2026-05-14T13:30:00Z)",
  "ok": true,
  "data": [
    {
      "id": 123456,
      "fullName": "Jane Doe",           # ← Real name visible
      "email": "j.doe@acme.com"         # ← Real email visible
    }
  ]
}

# After 2 hours (or you manually lock), redaction is back ON
$ nexudus config set pii-mode locked

✓ PII redaction locked

Locking PII manually

To immediately stop allowing PII in non-interactive mode:

nexudus config set pii-mode locked

This deletes the unlock session — no waiting for expiry. Every CLI command displays a status banner that clearly states whether PII redaction is ON or OFF:

Interactive terminal (PII visible)

🔓 PII redaction: OFF (interactive terminal)

┌─────────┬──────────┬──────────────────┬─────────────────┐
│ Id      │ FullName │ Email            │ TariffId        │
├─────────┼──────────┼──────────────────┼─────────────────┤
│ 1234567 │ Jane Doe │ j.doe@acme.com   │ 9876543         │
└─────────┴──────────┴──────────────────┴─────────────────┘

Piped/redirected (PII redacted)

🔒 PII redaction: ON (non-interactive)

[JSON/Markdown table with tokenized PII fields]

With unlock (PII visible + warning)

⚠️  PII redaction: OFF (unlocked until 2026-05-14T13:30:00Z)

[Full data with real PII values]

The banner is always printed before the main output, so you can quickly see the current state.

Threat model: What redaction protects against

Threat	Mitigation
PII flows to LLM	Tokens are sent instead of real values; LLM sees only opaque references
Agent bypasses redaction	No `--no-redact` flag exists. Redaction is structural based on TTY detection.
New field leaks	Schema annotations ensure new fields are redacted by default (fail-closed)
Summary text leaks	Summary fields containing PII are automatically redacted
Token reversal	Tokens are salted and stored locally; cannot derive real values without the local file

PII token storage

The CLI stores a local mapping of tokens to real values in ~/.nexudus/pii-tokens.json:

{
  "version": 1,
  "tokens": {
    "«PII:EMAIL:a3f2b1c9»": "j.doe@acme.com",
    "«PII:NAME:7e4d2f8a»": "Jane Doe",
    "«PII:PHONE:1b3c5d7e»": "+44 7700 900123"
  }
}

Important notes about token storage

Local only: Token mappings are stored only on your machine. They are never sent to the API or stored in logs.
Resolvable by CLI: When you pass a token as a command argument, the CLI looks it up in this file to recover the real value.
Per-installation: Each machine has its own salt and token store. Tokens from one machine won’t match another.
Human-readable for debugging: You can examine the file to understand which values have been tokenized.

Clearing tokens

To clear the local token store:

nexudus config set pii-clear-tokens

This deletes the token mapping file. Tokens in your command history will no longer resolve — be careful if you need to use them again.

Best practices for agents

✅ Do

Use tokens: Read tokenized output from list/get commands and pass tokens back to update/create commands.
Check redaction status: Always read piiRedaction and piiRedactionReason to know the current mode.
Cache tokens: Store tokens in your agent state if you need to reference the same entity across multiple commands.
Plan for token loss: Keep records of what you’re doing so you can re-fetch entities if needed.

❌ Don’t

Do not attempt to reverse-engineer tokens — they’re salted and hashed, not reversible.
Do not display tokens to end users as if they were real data — explain that they’re security redactions.
Do not request PII unlock — it requires human confirmation and cannot be automated.
Do not omit the --agent flag to bypass redaction — redaction is structural, not flag-based.
Do not store or log token mappings — the CLI handles storage locally.

Troubleshooting

I see tokens but want real data

Problem: Output is redacted when you need to see real values. Solution 1: Use an interactive terminal if possible — run the command directly in your shell. Solution 2: Unlock PII temporarily:

nexudus config set pii-mode unlocked --ttl 30m

I see “PII redaction: OFF” but expected tokens

Problem: You expected redaction but it’s not active. Reasons:

You’re in an interactive terminal — redaction is OFF by default for humans.
A previous unlock is still valid — check piiRedactionReason.
Your output is not being piped — TTY detection shows it’s interactive.

Solution: Check piiRedactionReason in the JSON envelope to understand why:

nexudus coworkers list --json | jq '.piiRedactionReason'

Tokens don’t resolve when I pass them back

Problem: Command fails with “invalid email” or similar when I use a token as an argument. Reasons:

Token was from a different machine/installation (different salt).
Token store was cleared (nexudus config set pii-clear-tokens).
Token format is incorrect or corrupted.

Solution: Re-fetch the entity fresh to get current tokens:

nexudus coworkers list --json | jq '.data[] | select(.id == 12345) | .email'

Unlock isn’t working

Problem: nexudus config set pii-mode unlocked fails or shows no confirmation prompt. Reason: Your input/output is redirected, so the CLI can’t show the interactive prompt. Solution: Run the unlock command in an interactive terminal without piping:

# This will fail (non-interactive):
echo "y" | nexudus config set pii-mode unlocked

# This works (interactive):
nexudus config set pii-mode unlocked
# [interactive prompt appears]

FAQ

Can I disable PII redaction?

No. Redaction is structural and based on TTY detection — it cannot be disabled by flags. However, you can unlock it temporarily with human confirmation if you genuinely need full PII in a non-interactive context.

Why are tokens not reversed when I pass them to a script?

Tokens are salted per installation and stored in ~/.nexudus/pii-tokens.json. If your script runs on a different machine or in a Docker container without that file, tokens won’t resolve. The CLI will reject invalid tokens with an error.

Can I extract all tokens from the token store?

Yes — the file is in plaintext JSON at ~/.nexudus/pii-tokens.json. You can read and parse it for debugging. Never share this file or its contents with others — it exposes real PII.

Is PII redaction available in all CLI commands?

Yes. Every entity query (list, get, search) respects the PII redaction mode. Create/update commands also resolve tokens transparently. If a command doesn’t show PII fields, it’s not related to redaction.

What happens if an agent passes an unknown token?

The CLI tries to resolve it from the token store. If not found, it passes the token literal to the API. The API validation will reject it (e.g., “invalid email format”), and the command fails with that error. This is intentional — prevents accidentally using stale tokens.

Can I share token mappings with colleagues?

Is PII redaction the same as encryption?

No. Redaction is a display-time transformation. PII is not encrypted in transit or at rest — the CLI and API use HTTPS. Redaction is an additional layer that hides PII from agent contexts and logs, using local tokenization and salting.

Output Modes — Understanding JSON, Markdown, and Agent output formats
Authentication — Credential storage and login
Agent Skills — Using the CLI with AI assistants

Overview

Using the CLI

Agent Skills

Reference

PII Redaction

PII Redaction

What is PII?

When is PII redacted?

How to detect redaction status

How PII looks when redacted

Token anatomy

Why tokens?

Using tokens in commands

Unlocking PII (time-limited override)

Unlock requirements

Example unlock workflow

Locking PII manually

PII redaction banner

Interactive terminal (PII visible)

Piped/redirected (PII redacted)

With unlock (PII visible + warning)

Threat model: What redaction protects against

PII token storage

Important notes about token storage

Clearing tokens

Best practices for agents

✅ Do

❌ Don’t

Troubleshooting

I see tokens but want real data

I see “PII redaction: OFF” but expected tokens

Tokens don’t resolve when I pass them back

Unlock isn’t working

FAQ

Overview

Using the CLI

Agent Skills

Reference

Documentation Index

​PII Redaction

​What is PII?

​When is PII redacted?

​How to detect redaction status

​How PII looks when redacted

​Token anatomy

​Why tokens?

​Using tokens in commands

​Unlocking PII (time-limited override)

​Unlock requirements

​Example unlock workflow

​Locking PII manually

​PII redaction banner

​Interactive terminal (PII visible)

​Piped/redirected (PII redacted)

​With unlock (PII visible + warning)

​Threat model: What redaction protects against

​PII token storage

​Important notes about token storage

​Clearing tokens

​Best practices for agents

​✅ Do

​❌ Don’t

​Troubleshooting

​I see tokens but want real data

​I see “PII redaction: OFF” but expected tokens

​Tokens don’t resolve when I pass them back

​Unlock isn’t working

​FAQ

​Related documentation

PII Redaction

What is PII?

When is PII redacted?

How to detect redaction status

How PII looks when redacted

Token anatomy

Why tokens?

Using tokens in commands

Unlocking PII (time-limited override)

Unlock requirements

Example unlock workflow

Locking PII manually

PII redaction banner

Interactive terminal (PII visible)

Piped/redirected (PII redacted)

With unlock (PII visible + warning)

Threat model: What redaction protects against

PII token storage

Important notes about token storage

Clearing tokens

Best practices for agents

✅ Do

❌ Don’t

Troubleshooting

I see tokens but want real data

I see “PII redaction: OFF” but expected tokens

Tokens don’t resolve when I pass them back

Unlock isn’t working

FAQ

Related documentation