Ninchi CLI & MCP

1. Find the organization ID in the dashboard URL — the segment after /dashboard/orgs/. Both forms work: a numeric ID (42) or the org's UUID public ID; newer dashboard URLs use the UUID form, and numeric IDs in existing configs keep working. The CLI does not currently list organizations.
2. Ask an org admin to open organization settings, find Programmatic Checks (CLI & MCP), and turn on “Enable CLI & MCP check submission.”
3. Programmatic-check quotas are hard limits per developer across a trailing 30-day window. A 429 response includes the time when the next check becomes available.

pipx install ninchi-cli

Add pipx applications to your shell PATH, open a new shell, and verify the executable.

pipx ensurepath
# Close and reopen your shell, then verify:
command -v ninchi
ninchi --help

command -v ninchi
# Use the printed absolute path in your MCP configuration.

ninchi login

1. The CLI prints a verification URL and an eight-character code such as XXXX-XXXX.
2. Open the URL, sign in, and approve the code at /dashboard/device.
3. The CLI polls until approval and saves the resulting personal access token.

Credentials are stored at ~/.config/ninchi/credentials with file mode 0600. NINCHI_CONFIG_DIR and XDG_CONFIG_HOME can change the location.

CI and manually created tokens

export NINCHI_API_TOKEN="ninchi_pat_..."
export NINCHI_ORG_ID=42

For CI, store the token as NINCHI_API_TOKEN. Create or revoke PATs from /dashboard/profile. Tokens carry checks:read and checks:write scopes by default, are shown once, are stored by Ninchi as HMAC digests, and stop working immediately after revocation.

# Working-tree diff (default)
ninchi check --org-id 42

# Other subject sources
git diff | ninchi check --stdin --org-id 42
ninchi check --staged --org-id 42
ninchi check --commit HEAD --org-id 42
ninchi check --file src/app.py --language python --org-id 42

# Reuse the org ID from your environment
export NINCHI_ORG_ID=42
ninchi check --staged

# Automation: answer non-interactively and emit JSON
ninchi check --staged \
  --answer "$ANSWER" \
  --actor agent_assisted \
  --json

# Inspect an existing challenge
ninchi result CHALLENGE_ID
ninchi result CHALLENGE_ID --json
ninchi history --limit 20
ninchi history --limit 20 --json

login supports --timeout, --api-url, and --json. check also supports --poll-interval and --timeout. result takes a challenge ID; history supports --limit. Put --json after the subcommand.

Pre-push hook

#!/usr/bin/env bash
set -euo pipefail

base="${NINCHI_BASE_REF:-origin/main}"
git diff --patch "$base"...HEAD | ninchi check \
  --stdin \
  --org-id "${NINCHI_ORG_ID:?set NINCHI_ORG_ID}"

Save this as .git/hooks/pre-push and make it executable. Omit --answer so the human answers interactively in the terminal.

Minimal GitHub Actions job

name: Ninchi check
on:
  pull_request:

jobs:
  ninchi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pipx install ninchi-cli
      - name: Submit Ninchi check and surface the challenge
        run: |
          git diff --patch origin/${{ github.base_ref }}...HEAD |
            ninchi check --stdin --json | tee ninchi-challenge.json || true
        env:
          NINCHI_API_TOKEN: ${{ secrets.NINCHI_API_TOKEN }}
          NINCHI_ORG_ID: ${{ vars.NINCHI_ORG_ID }}

Install the CLI directly from public PyPI. Store credentials in GitHub secrets, never in the workflow file. This job stops at submission by design: without --answer, the CLI prints the challenge JSON and exits 2. The answer must come from whoever authored the change — have authors answer interactively, for example via the pre-push hook or an MCP-capable editor. Do not wire a canned answer into CI: the question is generated per submission, and the answer window starts once the challenge is first viewed.

Use the absolute binary path as the primary configuration. Replace the placeholder with the output of command -v ninchi.

{
  "mcpServers": {
    "ninchi": {
      "command": "/absolute/path/from/command-v-ninchi",
      "args": ["mcp"]
    }
  }
}

Use a bare command only when the editor definitely inherits a PATH that contains ninchi.

{
  "mcpServers": {
    "ninchi": {
      "command": "ninchi",
      "args": ["mcp"]
    }
  }
}

MCP submissions stamp client_attribution: "mcp:<client>". This names the submitting channel and feeds AI-authorship analytics as a detection-floor signal; it does not by itself assert that AI assisted the work.

Still stuck? Visit Support and include the response's X-Request-ID when available.