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-cli

pnpm

pnpm add -g agentcloak-cli

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-cli -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, [email protected], +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

1. The CLI sends your text to the AgentCloak MCP Server using the Model Context Protocol (JSON-RPC over HTTPS)
2. 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
3. A unique record ID is returned that maps the placeholders back to the original values
4. To restore the original data, send the record ID along with the cloaked text back to the server using the uncloak command

Development

# Install dependencies
pnpm install

# Run in development mode (watches for changes)
pnpm dev -- -c "test message"

# Build
pnpm build

# Run tests
pnpm test

# Lint + build + test
pnpm all

License

ISC