Installation

Note

Installation and document extraction run locally. During scoutica scan, a remote-capable AI provider may send the full generated prompt and document text to its configured service. Review the provider and endpoint before scanning sensitive files.

Prerequisites

Before installing, make sure you have:

• Git — required to publish your card to GitHub
• Python 3.11 or newer — required for supported validation and scoring paths
• Strict validation dependencies — install explicitly with python3 -m pip install 'jsonschema[format]' PyYAML
• An AI CLI provider (macOS/Linux scan only) — at least one provider below must be installed for scoutica scan

The installers check Python and these packages before creating files. They do not run pip or mutate a global Python environment for you.

Platform capability matrix

Protocol version and CLI implementation version are separate identities.

Platform	Implementation	Capability set	Supported commands
macOS / Linux	POSIX 0.4.0	Full POSIX surface	All commands in the CLI reference
Windows PowerShell 5.1 / PowerShell 7	PowerShell implementation 0.1.0	windows-subset-v1	init, init --ai, validate, publish, info, help, version

Both implementations operate on Scoutica protocol 0.4.0. Windows does not currently provide the POSIX-only import, scan, resolve, preview, update, doctor, status, logs, org, role, evaluate, jobs, send, inbox, reply, deliver, register, or identity commands. Those commands exit 2 with an explicit unsupported diagnostic; a typo exits 1. Full Windows parity is parked for a future effort.

Supported AI providers

scoutica scan auto-detects installed providers in this order:

Provider	CLI command	Install	Use Case
Gemini CLI	gemini	google-gemini/gemini-cli	Best for multimodal analysis (e.g., parsing PDFs directly)
Claude Code	claude	anthropics/claude-code	Best for strict JSON adhering and rigorous schema compliance
OpenAI Codex	codex	openai/codex	Solid standard API toolchain integration
Mistral Vibe	vibe	mistralai/mistral-vibe	Interactive CLI provider for focused tasks
OpenCode	opencode	opencode-ai/opencode	Open source LLM bridging via bash
Ollama	ollama	ollama.com	Local when its configured endpoint is loopback
switchAILocal	ail	traylinx/switchAILocal	Fallback routing through your own AI proxy
OpenClaw	openclaw	openclaw/openclaw	Deep 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.

---

Option 1: Native Agent Install (Primary & Recommended)

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 on POSIX: 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. On Windows, it must stay within windows-subset-v1 and use init or the init --ai handoff instead of scan/registration.

🏢 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 on POSIX: 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. Employer/network commands are not in the current Windows subset.

---

Option 2: Script Install (Manual)

Run the installer

curl -fsSL https://raw.githubusercontent.com/traylinx/scoutica-protocol/main/install.sh | bash

irm https://raw.githubusercontent.com/traylinx/scoutica-protocol/main/install.ps1 | iex

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 schemas into ~/.scoutica/schemas for blazing fast offline validation.
4. Templates download: Pulls rules and markdown templates used for generation.
5. Helper download: Installs the helpers declared for the platform. The full POSIX install includes scoring, import, validation, scan, and safe-fetch helpers; Windows installs the resources declared for windows-subset-v1.
6. Path registration: Appends ~/.scoutica/bin to your PATH.

Reload your shell (macOS / Linux)

After installation, reload your shell configuration so the scoutica command is available:

source ~/.zshrc   # or source ~/.bashrc

Verify the installation

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

scoutica version
scoutica doctor

scoutica version
scoutica help

---

Manual macOS/Linux 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.

Clone the repository

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

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

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

# Python helpers the CLI shells out to (evaluate / import / validate) — MUST sit beside the binary
cp tools/scoring.py tools/import_aijs.py tools/validate_card.py ~/.scoutica/bin/

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

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

apt install poppler-utils

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.