@taplid/cli

Official CLI for the hosted Taplid audit API.

Use it as a thin hosted-service wrapper.

• Docs: https://taplid.com/docs
• Audit page: https://taplid.com/audit

Usage

npx @taplid/cli audit [request.json]

If you install the package locally use:

taplid audit [request.json]

Retrieve an audit

Every completed hosted audit returns an auditId. Anyone with the ID can retrieve the persisted public result. No API key is required for retrieval.

npx @taplid/cli audit get --audit-id AUD-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx --pretty

Treat the audit ID like a share link. Retrieval is a public lookup. Hosted audit results include an attestation object, which is the cryptographic proof layer.

Signed attestations

Hosted Taplid audit responses include an attestation object. It is an ES256-signed proof that Taplid issued the decision for the audited input and returned public result.

Public verification keys are available at:

https://api.taplid.com/.well-known/jwks.json

The attestation.token can be verified against the JWKS public key. The signed payload includes the auditId, auditMode, decision, trustScore, inputHash, and resultHash.

CI eval command

Use eval to run an audit and gate on trust score in CI. eval exits non-zero when the trust score is below --pass-threshold; audit (above) runs the audit and writes the full result JSON.

npx @taplid/cli eval request.json --api-key tap_live_... --pass-threshold 80

OpenAI-compatible verification endpoint

If you are already using an OpenAI SDK, Taplid also supports a compatibility route at /v1/chat/completions.

from openai import OpenAI

client = OpenAI(
  api_key="tap_live_...",
  base_url="https://api.taplid.com/v1",
)

The OpenAI-compatible route lives at POST https://api.taplid.com/v1/chat/completions.

Taplid is still a verifier, not a generator. On successful responses, always inspect response.taplid.decision before using response.choices[0].message.content.

Input

If provided, the input file contains the same request payload used by the audit page and API.

Example request.json:

{
  "context": "The number is 1.",
  "prompt": "What is the number?",
  "response": "The number is 2.",
  "auditMode": "standard"
}

Only response is required; context, prompt, and auditMode are optional.

Example response.json:

{
  "auditId": "AUD-XXX",
  "auditMode": "standard",
  "decision": "BLOCK",
  "trustScore": 20,
  "summary": "This answer conflicts with the provided context.",
  "issues": [
    {
      "message": "Contradicts the provided context.",
      "reason": "The context states one thing; the response says the opposite."
    }
  ],
  "nextStep": "Do not use this yet. Adjust the answer to match the provided context, then re-run the check.",
  "repairActions": [
    {
      "action": "Rewrite the answer so it aligns with the provided context.",
      "priority": "critical",
      "target": "response"
    }
  ],
  "claims": [
    {
      "text": "The number is 2.",
      "status": "contradicted",
      "evidence": [
        "Response value: 2",
        "Context value: 1"
      ]
    }
  ],
  "diagnosis": {
    "action": "revise_answer",
    "confidence": "high",
    "severity": "error",
    "nextSteps": [
      "Verify the answer is consistent with the provided context before re-running."
    ],
    "explanation": "The answer contradicts the provided context. Revise the answer to align with the source material before re-running the audit."
  },
  "claimStats": {
    "total": 1,
    "supported": 0,
    "unsupported": 0,
    "contradicted": 1,
    "evaluated": 1
  },
  "evidenceCoverage": 1,
  "metadata": {
    "auditDurationMs": 1,
    "claimsDetected": 1,
    "engine": "taplid",
    "version": "1"
  },
  "meta": {
    "policy": {
      "profileId": "balanced",
      "passThreshold": 80,
      "reviewThreshold": 60
    }
  },
  "requestId": "aud_XXX",
  "attestation": {
    "alg": "ES256",
    "kid": "taplid-es256-2026-06",
    "typ": "JWT",
    "issuer": "https://api.taplid.com",
    "issuedAt": "2026-06-12T21:28:52.000Z",
    "inputHash": "91f5884c9a9be6152e6d75534df82dada5965e7905bc80eca95df02970c6f3b1",
    "resultHash": "f95e77eb3224d987fa0baf35b5ee4c4e04029960cdcd6fd16c9171ffad929a7e",
    "token": "eyJhbGciOiJFUzI1NiIsImtpZCI6InRhcGxpZC1lczI1Ni0yMDI2LTA2IiwidHlwIjoiSldUIn0..."
  }
}

Output

By default the CLI writes the full audit result JSON to a sibling file:

• Input - request.json
• Output - request.response.json

When no input file is provided, default output is ./taplid.response.json.

Optional Flags

npx @taplid/cli audit request.json --out custom-response.json
npx @taplid/cli audit --response "Inline response only"
npx @taplid/cli audit --response-file-location ./bundle/response.txt
npx @taplid/cli audit --prompt "Inline prompt" --response-file-location ./bundle/response.txt
npx @taplid/cli audit request.json --audit-mode artifact
npx @taplid/cli audit request.json --api-url http://127.0.0.1:7000
npx @taplid/cli audit request.json --api-key your_api_key
npx @taplid/cli audit request.json --envfile .env.taplid
npx @taplid/cli audit request.json --pass-threshold 85 --review-threshold 65
npx @taplid/cli audit get --audit-id AUD-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx --pretty

• --out <path> writes the response JSON to a custom output path.
• --context <text> sets request context text for this run.
• --prompt <text> sets request prompt text for this run.
• --response <text> sets request response text for this run.
• --audit-mode <standard|artifact> overrides auditMode for this run. Default: artifact. Artifact mode is recommended for code reviews, PRs, implementation plans, SQL, configs, schemas, API contracts, and structured outputs checked against a supplied spec or policy.
• --context-file-location <path> resolves context text from a file.
• --prompt-file-location <path> resolves prompt text from a file.
• --response-file-location <path> resolves response text from a file.
• --api-url <url> overrides the default API origin.
• --api-key <key> is required for audit and eval and sends the taplid.com account API key. It is not required for audit get.
• --envfile <path> loads TAPLID env defaults from an explicit env file.
• --pass-threshold <0-100> overrides the pass threshold for this run.
• --review-threshold <0-100> overrides the review threshold for this run.
• --audit-id <AUD-...> retrieves a persisted hosted audit by ID with audit get.

Optional Environment Loading

The CLI supports three ways of providing TAPLID env values:

1. Shell or process environment
2. Explicit --envfile <path>
3. Auto-loaded local .env from the current working directory

If --envfile is provided, the CLI loads that file and does not auto-load the local .env.

If --envfile is not provided, the CLI checks process.cwd() for .env and continues silently if the file is absent.

If --envfile is provided but the file does not exist, the CLI fails fast.

Example shell usage:

$env:TAPLID_API_KEY = "your_api_key"
$env:TAPLID_AUDIT_MODE = "artifact"
npx @taplid/cli audit request.json

Example explicit env file usage:

npx @taplid/cli audit request.json --envfile .env.taplid

Optional Environment Defaults

Supported variables:

• TAPLID_PUBLIC_API_URL=
• TAPLID_API_KEY=
• TAPLID_CONTEXT=
• TAPLID_PROMPT=
• TAPLID_RESPONSE=
• TAPLID_CONTEXT_FILE_LOCATION=
• TAPLID_PROMPT_FILE_LOCATION=
• TAPLID_RESPONSE_FILE_LOCATION=
• TAPLID_AUDIT_MODE=
• TAPLID_REVIEW_THRESHOLD=
• TAPLID_PASS_THRESHOLD=

TAPLID_API_KEY is required for audit and eval (via flag or env). Blank env values are ignored. audit get does not require TAPLID_API_KEY.

context, prompt, and response are resolved per field as: CLI -> env/defaults -> request.json. Within each layer, inline text wins over matching *FileLocation. TAPLID_CONTEXT/TAPLID_PROMPT/TAPLID_RESPONSE override matching TAPLID_*_FILE_LOCATION values in the env layer. contextFileLocation, promptFileLocation, and responseFileLocation read file content as raw UTF-8 text regardless of extension (.txt, .json, etc.). request.json *FileLocation paths resolve from the request file directory, --envfile paths resolve from the env-file directory, and direct CLI/process-env paths resolve from process.cwd().

Precedence

• text fields (context, prompt, response): CLI -> env/defaults -> request.json
• non-text fields: CLI flags -> request.json -> shell env -> --envfile -> local .env -> built-in defaults

File format handling for context, prompt, and response inputs

Taplid treats context, prompt, and response file inputs as raw UTF-8 text. Supported examples include .txt, .md, .json, .log, .ndjson, .yaml, and .yml. These files are not parsed by type. Taplid reads the file contents as plain text and uses the resolved text value. This behavior is consistent across the audit page, CLI file-location flags, environment file-location variables, and request-payload file-location fields.

In JSON request files, use auditMode.

In CLI flags, use --audit-mode.

If both are provided, the CLI flag overrides the value in the request file.

Relative file-location paths resolve from:

• request.json directory for request payload file-location fields
• --envfile directory for env-file defaults
• process.cwd() for direct CLI flags and process environment values

If an explicit file-location path is provided and the file cannot be read, the CLI fails with a clear error unless an inline value for the same field is provided in that same layer.