Skip to main content

​
Syntax

scoutica scan <docs-folder> [options]

​
Options

​
docs-folder
string
required
Path to a directory containing your source documents (CV, certificates, portfolio, etc.).
​
--output, -o
string
Directory where the generated card files are written. Defaults to the current directory.
​
--with, -w
string
AI provider to use. One of: gemini, claude, codex, vibe, opencode, ollama, ail. When omitted, the CLI auto-detects the first installed provider in that order.
​
--clipboard, -c
flag
Instead of calling a local AI CLI, copy the generated prompt (with your documents included) to the clipboard. Use this if you want to paste it manually into an AI chat interface.

​
Usage examples

# Auto-detect installed AI CLI
scoutica scan ~/my-docs/

# Use a specific provider
scoutica scan ~/my-docs/ --with gemini
scoutica scan ~/my-docs/ --with claude
scoutica scan ~/my-docs/ --with ollama

# Write output to a specific directory
scoutica scan ~/my-docs/ --output ./my-card/

# Combine provider and output flags
scoutica scan ~/my-docs/ --with codex --output ./my-card/

# Copy prompt to clipboard instead of running an AI CLI
scoutica scan ~/my-docs/ --clipboard

​
Supported document formats

ExtensionNotes
.mdRead directly
.txtRead directly
.jsonRead directly
.yaml / .ymlRead directly
.csvRead directly
.html / .htmRead directly
.pdfExtracted via pdftotext, PyPDF2, or textutil
.docxExtracted via textutil (macOS) or python-docx
Install pdftotext for the best PDF extraction results:
brew install poppler       # macOS
apt install poppler-utils  # Linux

​
AI providers

Providers are auto-detected in the following priority order when --with is not specified:
PriorityProviderCLI commandInstall
1Gemini CLIgeminigoogle-gemini/gemini-cli
2Claude Codeclaudeanthropics/claude-code
3OpenAI Codexcodexopenai/codex
4Mistral Vibevibemistralai/mistral-vibe
5OpenCodeopencodeopencode-ai/opencode
6Ollamaollamaollama.com
7switchAILocalailtraylinx/switchAILocal
—Clipboard—Fallback when no CLI is found
If no provider is installed and --clipboard is not set, the CLI automatically falls back to clipboard mode.

​
Expected output

  → Scanning /Users/you/my-docs/...

    📄 resume.pdf (1420 words, extracted from PDF)
    📄 certifications.md (340 words)
    📄 portfolio.json (210 words)

  ✅ Found 3 documents

  → Generating card via gemini (local CLI — your data stays on your machine)...

  ✅ Response received from gemini

  → Writing card files to ./my-card...
  ✅ Created profile.json
  ✅ Created rules.yaml
  ✅ Created evidence.json
  ✅ Created SKILL.md
  ✅ Copied evaluation rule templates
  ✅ Created .gitignore (protects secrets from accidental commits)

​
Existing card backup

If the output directory already contains card files, scan automatically backs them up before overwriting: 
  ⚠️  Existing card files found in ./my-card/:
    • profile.json
    • rules.yaml

  ✅ Backed up existing files to .backup/20260323_142501/
Privacy: Your documents are piped directly to the local AI CLI running on your machine. No data is sent to any cloud API. The raw AI response is saved temporarily as .scan_response_raw.txt and deleted immediately after the card files are written.

​
Clipboard mode

When --clipboard is used (or no AI CLI is installed), the full prompt — including the contents of all your documents — is copied to your clipboard or saved as scoutica_prompt.txt in the output directory. 
scoutica scan ~/my-docs/ --clipboard
Paste it into any AI assistant and save the returned JSON files to your card directory.

​
Next steps

scoutica info ./my-card      # review the generated card
scoutica validate ./my-card  # check for schema errors
scoutica publish ./my-card   # push to GitHub