---
name: sygal-cli
description: Use when the user wants to convert documents (PDF, Word, Excel, PowerPoint, images, web pages) to clean Markdown or JSON, especially to prepare files for an AI agent's own memory or context. Installs Sygal CLI if missing, converts files, and handles OCR for images and scanned documents.
---

# Sygal CLI

Sygal CLI converts any document or web page to clean Markdown and/or JSON, locally. Use it whenever the user hands you a document, a folder of documents, or a URL and wants it turned into clean text to read, store, or index.

## First use: check and install

1. Check Node.js: run `node --version`. Sygal CLI needs Node.js 20 or later.
   - If missing or too old, tell the user to install it from https://nodejs.org. Don't install a system runtime yourself without asking first.
2. Check Sygal CLI: run `sygal --version`.
   - If not found, install it: `npm install -g sygal-cli`. This is a normal package install, safe to run without asking.

## Converting documents

```
sygal convert <path-or-url> [options]
```

Key options:
- `--format md|json|both` (default `md`)
- `-o, --output <dir>` (default: next to the source file)
- `--advanced` (also OCR images embedded inside the document)
- `--pdf-ocr all|first|page` (for scanned PDFs with no extractable text)
- `--translate <locale>` (translate the result: fr, en, it, de, es)
- `--json` (strict machine-readable output on stdout, exit code 1 on failure)

If the user hasn't said where they want the output, ask once (md, json, or both; same folder or a dedicated output folder) and remember the answer for the rest of the session. Don't ask again for every file.

## OCR: images and scanned documents

By default, don't ask the user to set up an OCR provider or API key upfront. Use deferred OCR so you transcribe images yourself, at zero extra cost:

```
sygal convert <path> --advanced --ocr defer --json
```

This extracts images next to the source, marks their position in the Markdown, and lists them as `deferred` in the JSON output. Read each image yourself, then feed the transcriptions back:

```
sygal inject <file>.md --transcripts transcriptions.json
```

`transcriptions.json` format: `[{ "index": 1, "text": "...", "provider": "agent" }, ...]`.

Only mention a dedicated OCR provider if the batch is large (roughly more than 8-10 deferred images in one job). In that case, mention it without blocking the work: a dedicated provider (Mistral is the cheapest, OpenAI is the default, Claude/NVIDIA/Gemini also supported) may cost less for that volume than transcribing every image yourself. Give the commands but never handle the API key in chat:

```
sygal config set-ocr-provider <openai|mistral|claude|nvidia|gemini>
sygal config set-api-key <provider>
```

`set-api-key` reads the key from stdin. Tell the user to run it themselves in their own terminal. Never ask the user to paste an API key into the conversation.

## Error codes (with --json)

`unsupported_format`, `api_key_missing`, `invalid_api_key`, `rate_limited`, `network_error`, `scanned_pdf_detected` (retry with `--pdf-ocr`), `ocr_call_limit_exceeded`, `license_expired`, `sidecar_down`, `sidecar_not_found`, `timeout`.

## Licence

Sygal CLI starts with a 14-day free trial automatically, no card needed. After that:

```
sygal license activate <key>
sygal license status
sygal license deactivate
```

One licence key gives a fixed number of seats (1 for the standalone CLI licence, more for team packs). Each activation, whether it's the desktop app or the CLI, uses one seat. The user can buy a licence at https://sygal.lemonsqueezy.com.