AgentCloak CLI
Command-line tool for anonymizing personally identifiable information (PII) using the InCountry AgentCloak MCP Server.
AgentCloak replaces sensitive data — names, ages, locations, medical terms, financial information, and more — with indexed category placeholders (e.g., [NamePlaceholder1], [LocationPlaceholder1]). This CLI lets you cloak and uncloak text directly from your terminal or shell scripts.
Prerequisites
- Node.js >= 20.6.0
- An AgentCloak MCP Server (created via the InCountry Portal)
- Your MCP Server URL and API key
Installation
npm
npm install -g agentcloak
Configuration
Create a .env file in the directory where you run the tool, or export environment variables:
INC_MCP_URL=https://your-mcp-server-url.incountry.io
INC_MCP_API_KEY=your-api-key
Optional configuration
| Variable | Default | Description |
|---|---|---|
AGENTCLOAK_RETRY_MAX_ATTEMPTS | 3 | Maximum number of request attempts |
AGENTCLOAK_RETRY_INITIAL_DELAY_MS | 250 | Initial retry delay in milliseconds |
AGENTCLOAK_RETRY_MAX_DELAY_MS | 2000 | Maximum retry delay in milliseconds |
AGENTCLOAK_RETRY_BACKOFF_MULTIPLIER | 2 | Exponential backoff multiplier |
AGENTCLOAK_REQUEST_TIMEOUT_MS | 30000 | Request timeout in milliseconds |
AGENTCLOAK_RETRY_STATUS_CODES | 408,425,429,500,502,503,504 | Comma-separated HTTP status codes to retry |
Usage
Running with npx (no install)
npx agentcloak -c "John Doe, age 32, lives in Berlin"
Running installed version
agentcloak -c "John Doe, age 32, lives in Berlin"
Commands
| Flag | Short | Description |
|---|---|---|
--cloak <text> | -c | Cloak the provided text |
--uncloak <id> <text> | -u | Uncloak text using the given record ID |
--output <format> | -o | Output format (see below) |
--install <harness> | Install AI agent skill file |
Output formats
| Format | Description |
|---|---|
colored | Human-readable with colors (default) |
monochrome | Human-readable without colors |
plain | Raw data only — ideal for piping |
json | JSON object |
csv | CSV with header row |
In plain mode, the cloak command prints the record ID to stderr and the cloaked content to stdout, making it easy to pipe cloaked output directly into files.
Examples
Simple cloak
agentcloak -c "Patient Jane Smith, female, 45 years old, diagnosed with Type 2 Diabetes"
Output:
ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Cloaked: Patient [NamePlaceholder1], [GenderPlaceholder1], [AgePlaceholder1] years old, diagnosed with [MedicalPlaceholder1]
Simple uncloak
agentcloak -u a1b2c3d4-e5f6-7890-abcd-ef1234567890 "Patient [NamePlaceholder1], [GenderPlaceholder1], [AgePlaceholder1] years old, diagnosed with [MedicalPlaceholder1]"
Cloak text from a file
cat patient_notes.txt | agentcloak -c
Cloak and save to file (plain mode)
agentcloak -c "John Doe lives at 123 Main St, NYC" -o plain > cloaked.txt
# Record ID is printed to stderr
# cloaked.txt contains only the anonymized text
Capture both ID and cloaked text separately
agentcloak -c "Jane Doe, age 28" -o plain > cloaked.txt 2> id.txt
Uncloak from a file
cat cloaked.txt | agentcloak -u "$(cat id.txt)"
JSON output for programmatic use
agentcloak -c "Account holder: Bob Smith, account #4532-1234-5678-9012" -o json
Output:
{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","result":"Account holder: [NamePlaceholder1], account #[FinancialPlaceholder1]"}
Extract data from a JSON file with jq and cloak
jq -r '.user.bio' profile.json | agentcloak -c -o json
Process multiple records from a JSON array
jq -r '.patients[].notes' records.json | agentcloak -c
Pipe cloak result into another command
agentcloak -c "Dr. Sarah Connor, Therapist, Los Angeles" -o plain | \
curl -X POST https://api.example.com/notes -d @-
Use in a shell script pipeline
#!/usr/bin/env bash
set -euo pipefail
# Step 1: Cloak sensitive data, capture ID and cloaked text
RESULT=$(agentcloak -c -o json < prompt.txt)
RECORD_ID=$(echo "$RESULT" | jq -r '.id')
CLOAKED=$(echo "$RESULT" | jq -r '.result')
# Step 2: Send cloaked text to an LLM, then uncloak the response
echo "$CLOAKED" | llm-cli generate | agentcloak -u "$RECORD_ID"
CSV output for spreadsheets
agentcloak -c "Alice, 29, alice@example.com, +1-555-0123" -o csv
Output:
id,result
a1b2c3d4-e5f6-7890-abcd-ef1234567890,"[NamePlaceholder1], [AgePlaceholder1], [EmailPlaceholder1], [PhonePlaceholder1]"
AI Agent Integration
AgentCloak ships with a skill file that teaches AI coding agents how to use the CLI. Install it into your project's agent configuration:
agentcloak --install <harness>
Supported harnesses
| Harness | Target path | Agent |
|---|---|---|
opencode | .opencode/skills/agentcloak.md | OpenCode |
claude | .claude/commands/agentcloak.md | Claude Code |
codex | .codex/agentcloak.md | OpenAI Codex |
gemini | .gemini/agentcloak.md | Gemini CLI |
qwen | .qwen/skills/agentcloak.md | Qwen Code |
copilot | .github/instructions/agentcloak.md | GitHub Copilot |
cursor | .cursor/rules/agentcloak.md | Cursor |
The installer looks for the harness directory in the current working directory first, then falls back to the home directory. If the directory doesn't exist, it exits with an error prompting you to initialize the harness first.
How it works
- The CLI sends your text to the AgentCloak MCP Server using the Model Context Protocol (JSON-RPC over HTTPS)
- The server identifies PII categories (names, ages, locations, etc.) and replaces them with indexed placeholders (e.g.,
[NamePlaceholder1],[LocationPlaceholder2]) according to your server's cloak settings - A unique record ID is returned that maps the placeholders back to the original values
- To restore the original data, send the record ID along with the cloaked text back to the server using the uncloak command