Skip to main content
Everything runs locally. Your documents and data never leave your machine — the scan command pipes your files to a local AI CLI with no cloud API calls.

​
Prerequisites

Before installing, make sure you have:
  • Git — required to publish your card to GitHub
  • Python 3 — required for card validation (python3 --version to check)
  • An AI CLI provider — at least one of the providers below must be installed for scoutica scan to work

​
Supported AI providers

scoutica scan auto-detects installed providers in this order:
ProviderCLI commandInstallUse Case
Gemini CLIgeminigoogle-gemini/gemini-cliBest for multimodal analysis (e.g., parsing PDFs directly)
Claude Codeclaudeanthropics/claude-codeBest for strict JSON adhering and rigorous schema compliance
OpenAI Codexcodexopenai/codexSolid standard API toolchain integration
Mistral Vibevibemistralai/mistral-vibeQuick, local, specialized tasks without high compute
OpenCodeopencodeopencode-ai/opencodeOpen source LLM bridging via bash
Ollamaollamaollama.com100% offline local models for absolute privacy
switchAILocalailtraylinx/switchAILocalFallback routing through your own AI proxy
OpenClawopenclawopenclaw/openclawDeep AI agent integrations and swarm coordination
You can also use --clipboard mode to copy the scan prompt to any AI chat without installing a local provider.
The Scoutica Protocol is designed to be fully operated by autonomous AI agents (like Claude Code, Cursor, OpenCode, or OpenClaw). The easiest and fastest way to install the CLI and configure the protocol is natively via your agent’s terminal. Choose your persona below and copy the exact prompt into your AI agent:

​
🧑‍💻 For Candidates (Job Seekers)

If you want to generate a Skill Card to find a job on your own terms: 
Read https://raw.githubusercontent.com/traylinx/scoutica-protocol/main/SKILL.md and follow the instructions to set up Scoutica Protocol natively.
What the agent will do: It reads the protocol specs, installs the CLI, finds your CV documents, extracts your skills into a Skill Card, validates the JSON schemas, and registers you on the Live Network for discovery.

​
🏢 For Recruiters & Employers

If you want to establish an organizational identity to hire and discover candidates autonomously: 
Read https://raw.githubusercontent.com/traylinx/scoutica-protocol/main/RECRUITER_SKILL.md and follow the instructions to set up the Scoutica Employer Network natively.
What the agent will do: It reads the employer specs, installs the CLI, scaffolds your Recruiter Card, creates structured job roles, verifies your domain, and starts searching the registry to evaluate and message matching candidates securely.

​
Option 2: Script Install (Manual)

1

Run the installer

curl -fsSL https://raw.githubusercontent.com/traylinx/scoutica-protocol/main/install.sh | bash
The installer performs the following background tasks automatically:
  1. Scaffold config directory: Creates ~/.scoutica/ structure.
  2. Binary download: Puts the core executable in ~/.scoutica/bin.
  3. Schemas download: Pulls v1 schemas into ~/.scoutica/schemas for blazing fast offline validation.
  4. Templates download: Pulls rules and markdown templates used for generation.
  5. Path registration: Appends ~/.scoutica/bin to your PATH.
2

Reload your shell (macOS / Linux)

After installation, reload your shell configuration so the scoutica command is available:
source ~/.zshrc   # or source ~/.bashrc
3

Verify the installation

Run a diagnostic to ensure the binary is successfully in your path:
scoutica version
scoutica doctor

​
Manual Installation

For users who prefer exhaustive control over their system configuration and want to avoid piping a remote script directly to bash, you can install Scoutica Protocol manually.
1

Clone the repository

git clone https://github.com/traylinx/scoutica-protocol.git
cd scoutica-protocol
2

Create the application directory

Scoutica expects its templates and schemas to live in the SCOUTICA_HOME path (~/.scoutica/ by default).
mkdir -p ~/.scoutica/bin
mkdir -p ~/.scoutica/schemas
mkdir -p ~/.scoutica/templates/rules
3

Copy core files

Move the CLI tool and protocol assets into your home directory:
cp tools/scoutica ~/.scoutica/bin/scoutica
chmod +x ~/.scoutica/bin/scoutica

cp schemas/*.json ~/.scoutica/schemas/
cp protocol/templates/*.txt ~/.scoutica/templates/
cp protocol/templates/rules/*.md ~/.scoutica/templates/rules/
4

Update your PATH

Add the binary to your shell’s binary path. E.g. for ZSH:
echo 'export PATH="$HOME/.scoutica/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

​
Keeping the CLI up to date

Updates are natively handled by the CLI through the update daemon. Unlike Node.js or Homebrew packages, it manages itself cleanly inside of ~/.scoutica. 
scoutica update
This will compare your local VERSION against the remote GitHub stable branch. If an update exists, it streams the latest core assets instantly. No node modules, no dependencies.

​
Troubleshooting

scoutica: command not found Ensure that ~/.scoutica/bin actively exists in your $PATH. Check it by running: 
echo $PATH | grep scoutica
PDF text extraction fails during scan If you feed PDF CVs into scoutica scan ~/CV, it requires pdftotext. 
brew install poppler
Empty response from provider Ensure your local AI provider is configured and authenticated. 
gemini --version

​
What’s next

Now that the CLI is installed seamlessly, let’s create your first profile:

Quick start

Walk through the complete flow: scan, validate, and publish your Skill Card in 5 minutes.