oto-cli 1.3.0__tar.gz → 1.4.0__tar.gz

oto_cli-1.4.0/.github/workflows/deploy.yml

@@ -0,0 +1,34 @@
+name: Deploy
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+
+concurrency:
+  group: deploy-prod
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to tuls.me
+        uses: appleboy/ssh-action@v1.0.3
+        with:
+          host: 51.15.225.121
+          username: root
+          key: ${{ secrets.SSH_PRIVATE_KEY }}
+          script: |
+            set -e
+            cd /opt/oto-cli
+            git fetch origin main
+            git reset --hard origin/main
+            # oto-cli is installed editable via `pip install -e .` in oto-mcp's
+            # venv — no reinstall needed on pull unless deps change. We still
+            # restart oto-mcp so new modules (e.g. oto.tools.culture) are
+            # picked up by the registered MCP tools.
+            systemctl restart oto-mcp
+            sleep 3
+            systemctl is-active --quiet oto-mcp || (journalctl -u oto-mcp -n 50 --no-pager; exit 1)
+            journalctl -u oto-mcp -n 10 --no-pager

{oto_cli-1.3.0 → oto_cli-1.4.0}/CLAUDE.md

@@ -2,7 +2,7 @@
 
 CLI toolkit for AI agents — covers the long tail of SaaS APIs that don't have a CLI.
 
-Repo: `AlexisLaporte/oto`. Package: `oto-cli` on PyPI (v1.1.0). Command: `oto`.
+Repo: `otomata-tech/oto-cli`. Package: `oto-cli` on PyPI (v1.1.0). Command: `oto`.
 
 ## Philosophy
 
@@ -30,7 +30,9 @@ oto/
 │   │   ├── notion.py           # search, page, database
 │   │   ├── browser.py          # linkedin, crunchbase, pappers, indeed, g2, google
 │   │   ├── reddit.py           # Reddit JSON API (subreddit, search, post)
-│   │   ├── sirene.py           # SIRENE API (search, get, stock)
+│   │   ├── fr.py               # données entreprise FR (fr_*) : recherche, bilans INPI, BODACC + sirene stock
+│   │   ├── dvf.py              # valeurs foncières (immobilier) : stats/comparables €/m² par commune ou adresse
+│   │   ├── culture.py          # Min. Culture open data (Opendatasoft) — sub-namespace `spectacle` (LES)
 │   │   ├── search.py           # facade: dispatches to serper or browser via config
 │   │   ├── serper.py           # direct Serper API (web, news, scrape, suggestions)
 │   │   ├── enrichment.py       # kaspr, hunter, lemlist
@@ -42,9 +44,13 @@ oto/
 │   │   ├── zohodesk.py         # Zoho Desk (tickets/support)
 │   │   ├── company.py          # SIREN lookup multi-source
 │   │   ├── whatsapp.py         # WhatsApp messaging
+│   │   ├── slack.py            # Slack — send/read/list-channels/dm (bot+user tokens)
 │   │   ├── audio.py            # audio recording, transcription
-│   │   ├── gemini.py           # Gemini image generation
+│   │   ├── gemini.py           # Gemini image generation (gemini-3-pro-image)
+│   │   ├── openai.py           # OpenAI image generation (gpt-image-2)
 │   │   ├── pdf.py              # markdown → PDF via pandoc + weasyprint (bundled template)
+│   │   ├── data.py             # Datastore (per-user Google Sheets via mcp.oto.ninja, OTO_API_KEY)
+│   │   ├── ninja.py            # façade mcp.oto.ninja: secrets per-user (LinkedIn/Crunchbase/API keys), OTO_API_KEY
 │   │   ├── config.py           # config & secrets management
 │   │   └── skills.py           # Claude Code skills (enable/disable)
 │   └── tools/                  # API clients
@@ -54,12 +60,16 @@ oto/
 │       ├── reddit/              # Reddit JSON API (no auth)
 │       ├── whatsapp/           # Node.js bridge (whatsapp-web.js)
 │       ├── sirene/             # INSEE SIRENE API
+│       ├── culture/            # OpendatasoftClient générique + SpectacleClient (LES)
 │       ├── serper/             # Google search (web, news)
 │       ├── anthropic/          # Admin API (usage, costs)
 │       ├── pennylane/          # Accounting
 │       ├── attio/              # Attio CRM
+│       ├── datastore/          # HTTP client → mcp.oto.ninja /api/datastore/*
+│       ├── ninja/              # HTTP client → mcp.oto.ninja /api/settings/* (secrets per-user)
 │       ├── kaspr/, hunter/, lemlist/  # Enrichment & outreach
 │       ├── zohodesk/           # Zoho Desk (tickets/support)
+│       ├── gemini/, openai/    # Image generation (Gemini 3 Pro, gpt-image-2)
 │       ├── pdf/                # pandoc+weasyprint wrapper, bundled CSS template (sober editorial)
 │       └── folk/, zoho/, slack/, resend/  # CRM & messaging
 ├── skills/                     # Claude Code skills
@@ -107,14 +117,19 @@ Key rules:
 
 ## Secrets & Config
 
-Provider-based resolution, configured via `oto config provider secrets <file|scaleway>`:
-1. Environment variables (always, highest priority)
-2. Configured provider: **file** (`.otomata/secrets.env` project → user) or **Scaleway** Secret Manager
+Provider-based resolution (`oto config provider secrets <sops|file|scaleway>`) :
+1. Env vars (always, highest priority)
+2. Configured provider:
+   - **sops** (default) — SOPS+age. `sops_dir` (multi-file, walks `*.yaml`
+     recursively, merges flat with warning on duplicate keys) or `sops_file`
+     (mono-file legacy). Default dir: `~/.otomata/secrets/`.
+   - **file** — `.otomata/secrets.env` project → user
+   - **scaleway** — Secret Manager
 3. Default value
 
 ```bash
 oto config                        # show providers + secrets status
-oto config provider secrets file  # switch to file-based secrets
+oto config provider secrets sops  # switch to SOPS (default)
 oto config provider search serper # switch search to serper (default) or browser
 oto config secrets-push           # upload local secrets.env → Scaleway
 oto config secrets-pull           # download Scaleway → local secrets.env
@@ -149,13 +164,18 @@ oto skills enable oto-google       # enable one
 oto skills disable oto-pennylane   # disable one
 ```
 
-## Release
+## Deploy
 
-Package: `oto-cli` on PyPI. PyPI token in `pass otomata/PYPI_TOKEN`.
+Push main déclenche `.github/workflows/deploy.yml` qui SSH tuls.me, `git reset --hard origin/main` dans `/opt/oto-cli`, puis `systemctl restart oto-mcp` (oto-cli est installé editable dans le venv d'oto-mcp ; sans restart les modules déjà importés ne pickent pas les nouveaux). Pas de release PyPI requise pour propager un nouveau connecteur.
+
+## Release PyPI (rare)
+
+Pour publier sur PyPI (autres utilisateurs hors infra Otomata). PyPI token in SOPS (`PYPI_TOKEN`).
 
 ```bash
 # Bump version in oto/__init__.py, then:
-hatch build && hatch publish -u __token__ -a "$(pass otomata/PYPI_TOKEN)"
+hatch build && hatch publish -u __token__ \
+  -a "$(sops --decrypt --extract '["PYPI_TOKEN"]' ~/.otomata/secrets/secrets/secrets.yaml)"
 gh release create vX.Y.Z --generate-notes dist/*
 ```
 

{oto_cli-1.3.0 → oto_cli-1.4.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: oto-cli
-Version: 1.3.0
+Version: 1.4.0
 Summary: CLI toolkit for AI agents — covers the long tail of SaaS APIs that don't have a CLI
-Project-URL: Repository, https://github.com/AlexisLaporte/oto
+Project-URL: Repository, https://github.com/otomata-tech/oto-cli
 Author: Alexis Laporte
 License-Expression: MIT
 License-File: LICENSE
@@ -71,8 +71,8 @@ pipx install "oto-cli[google,browser]"
 pipx install "oto-cli[all]"
 
 # Development
-git clone https://github.com/AlexisLaporte/oto.git
-cd oto && pip install -e ".[all]"
+git clone https://github.com/otomata-tech/oto-cli.git
+cd oto-cli && pip install -e ".[all]"
 ```
 
 ## Connectors
@@ -95,7 +95,8 @@ cd oto && pip install -e ".[all]"
 | `oto zohodesk` | Zoho Desk (tickets, threads, contacts, departments) | — |
 | `oto company` | French company lookup (multi-source) | — |
 | `oto audio` | Audio recording, transcription, summaries | — |
-| `oto gemini` | Image generation (text-to-image, editing) | — |
+| `oto gemini` | Image generation via Gemini 3 Pro (text-to-image, editing) | — |
+| `oto openai` | Image generation via gpt-image-2 (text-to-image, editing) | — |
 | `oto config` | Configuration & secrets management | — |
 
 Connectors without an "Extra" only need `requests` (included in base install).
@@ -127,8 +128,11 @@ oto google gmail-search "from:bob" -a myaccount
 # Browse LinkedIn
 oto browser linkedin profile https://linkedin.com/in/someone
 
-# French company data
+# French company data — INSEE SIRENE
 oto sirene search "fintech"
+
+# Enriched data via data.gouv recherche-entreprises (with --idcc filter by convention collective)
+oto sirene entreprises --idcc 1285,3090 --naf 90.01Z --dept 75
 ```
 
 ## Skills for AI agents

{oto_cli-1.3.0 → oto_cli-1.4.0}/README.md

@@ -28,8 +28,8 @@ pipx install "oto-cli[google,browser]"
 pipx install "oto-cli[all]"
 
 # Development
-git clone https://github.com/AlexisLaporte/oto.git
-cd oto && pip install -e ".[all]"
+git clone https://github.com/otomata-tech/oto-cli.git
+cd oto-cli && pip install -e ".[all]"
 ```
 
 ## Connectors
@@ -52,7 +52,8 @@ cd oto && pip install -e ".[all]"
 | `oto zohodesk` | Zoho Desk (tickets, threads, contacts, departments) | — |
 | `oto company` | French company lookup (multi-source) | — |
 | `oto audio` | Audio recording, transcription, summaries | — |
-| `oto gemini` | Image generation (text-to-image, editing) | — |
+| `oto gemini` | Image generation via Gemini 3 Pro (text-to-image, editing) | — |
+| `oto openai` | Image generation via gpt-image-2 (text-to-image, editing) | — |
 | `oto config` | Configuration & secrets management | — |
 
 Connectors without an "Extra" only need `requests` (included in base install).
@@ -84,8 +85,11 @@ oto google gmail-search "from:bob" -a myaccount
 # Browse LinkedIn
 oto browser linkedin profile https://linkedin.com/in/someone
 
-# French company data
+# French company data — INSEE SIRENE
 oto sirene search "fintech"
+
+# Enriched data via data.gouv recherche-entreprises (with --idcc filter by convention collective)
+oto sirene entreprises --idcc 1285,3090 --naf 90.01Z --dept 75
 ```
 
 ## Skills for AI agents

oto_cli-1.4.0/docs/installation.md

@@ -0,0 +1,135 @@
+# Installation
+
+`oto` is a CLI toolkit. Install it once with `pipx`, then every connector is a
+sub-command (`oto google`, `oto linkedin`, …). Each connector also ships a
+`SKILL.md` so your AI agent (Claude Code, Cursor, …) knows how to drive it.
+
+## Prerequisites
+
+- **Python 3.10+**
+- **pipx** (recommended) — isolates the CLI in its own venv
+- **Google Chrome** — required only for the `browser` connectors (LinkedIn,
+  Crunchbase, Indeed, …). `oto` drives your installed Chrome; if Chrome is
+  absent see [Troubleshooting](#browser-no-chromechromium-found).
+
+## Install pipx
+
+```bash
+# Debian/Ubuntu
+sudo apt install pipx && pipx ensurepath
+# Fedora
+sudo dnf install pipx && pipx ensurepath
+# macOS
+brew install pipx && pipx ensurepath
+# Windows (PowerShell)
+pip install --user pipx && python -m pipx ensurepath
+```
+
+Restart your terminal after `ensurepath`.
+
+## Install oto
+
+```bash
+# Base CLI (API connectors that only need HTTP)
+pipx install oto-cli
+
+# With the browser connectors (LinkedIn, Crunchbase, …)
+pipx install "oto-cli[browser]"
+
+# With Google (Gmail, Drive, Sheets, …)
+pipx install "oto-cli[google,browser]"
+
+# Everything
+pipx install "oto-cli[all]"
+```
+
+Verify:
+
+```bash
+oto --help
+```
+
+## LinkedIn setup
+
+LinkedIn no longer accepts an injected `li_at` cookie (its TLS fingerprinting
+rejects a session that wasn't created by the same browser). The reliable method
+is a **persistent browser profile** you log into once.
+
+```bash
+# One-time: opens a real Chrome window — log in by hand, then CLOSE the window.
+oto linkedin login --profile ~/.config/browser/linkedin
+```
+
+> `login` opens a visible (headed) browser, so it needs a graphical session
+> (a desktop, or VNC on a headless server). Log in fully (including 2FA), confirm
+> you land on your feed, then close the window — the session is saved in the
+> profile directory.
+
+Afterwards, pass that profile to every LinkedIn command:
+
+```bash
+oto linkedin search-people "head of finance" --profile ~/.config/browser/linkedin
+oto linkedin connect "https://www.linkedin.com/in/john-doe/" --note "Bonjour …" \
+  --profile ~/.config/browser/linkedin
+```
+
+No API key or secret is required for LinkedIn when you use a logged-in profile.
+See the `oto-browser` skill for the full command set (`oto skills show oto-browser`).
+
+## Configuration & secrets
+
+Connectors that hit third-party APIs (Serper, Hunter, Attio, Pennylane, …) need
+credentials. `oto` resolves a secret in this order: **environment variable →
+configured provider → default**. The simplest provider is a flat file:
+
+```bash
+mkdir -p ~/.otomata
+printf 'SERPER_API_KEY=xxx\nHUNTER_API_KEY=yyy\n' >> ~/.otomata/secrets.env
+oto config provider secrets file   # use the file provider
+oto config                         # show providers + which secrets are set
+```
+
+LinkedIn-via-profile needs none of this.
+
+## Skills (for AI agents)
+
+Each connector's `SKILL.md` is an instruction manual for your agent. Symlink them
+into Claude Code:
+
+```bash
+oto skills enable --all      # or: oto skills enable oto-browser
+oto skills list
+```
+
+## Update / uninstall
+
+```bash
+pipx upgrade oto-cli
+pipx uninstall oto-cli
+```
+
+## Troubleshooting
+
+### `oto: command not found`
+Run `pipx ensurepath` and restart the terminal.
+
+### Browser: no Chrome/Chromium found
+`oto` prefers your installed Google Chrome. If you don't have Chrome, install a
+Chromium for Patchright inside the CLI's venv:
+
+```bash
+~/.local/share/pipx/venvs/oto-cli/bin/patchright install chromium
+```
+
+(On macOS/Windows the path under `pipx environment --value PIPX_LOCAL_VENVS` is
+the equivalent.)
+
+### LinkedIn: "session expired — cookie li_at is no longer valid"
+The profile's session lapsed. Re-run the login:
+
+```bash
+oto linkedin login --profile ~/.config/browser/linkedin
+```
+
+### Python version error
+Ensure Python 3.10+: `python3 --version`.

{oto_cli-1.3.0 → oto_cli-1.4.0}/oto/__init__.py

@@ -1,3 +1,3 @@
 """Oto - CLI tools for automation."""
 
-__version__ = "1.3.0"
+__version__ = "1.4.0"

{oto_cli-1.3.0 → oto_cli-1.4.0}/oto/commands/attio.py

@@ -134,6 +134,49 @@ def add_person(
     _out(result.get("data", {}))
 
 
+@app.command("update-person")
+def update_person(
+    record_id: str = typer.Argument(..., help="Record ID"),
+    first_name: Optional[str] = typer.Option(None, "--first", help="First name (requires --last)"),
+    last_name: Optional[str] = typer.Option(None, "--last", "-l", help="Last name (requires --first)"),
+    email: Optional[str] = typer.Option(None, "--email", "-e"),
+    phone: Optional[str] = typer.Option(None, "--phone"),
+    job_title: Optional[str] = typer.Option(None, "--title", "-t"),
+    company: Optional[str] = typer.Option(None, "--company", "-c", help="Company name (matches existing)"),
+    linkedin: Optional[str] = typer.Option(None, "--linkedin", help="LinkedIn URL"),
+):
+    """Update a contact. Multi-value fields (email/phone) are replaced."""
+    values = {}
+    if first_name or last_name:
+        if not (first_name and last_name):
+            print("To change the name, pass both --first and --last")
+            raise typer.Exit(1)
+        full = f"{first_name} {last_name}".strip()
+        values["name"] = [{"first_name": first_name, "last_name": last_name, "full_name": full}]
+    if email:
+        values["email_addresses"] = [{"email_address": email}]
+    if phone:
+        values["phone_numbers"] = [{"phone_number": phone}]
+    if job_title:
+        values["job_title"] = [{"value": job_title}]
+    if linkedin:
+        values["linkedin"] = [{"value": linkedin}]
+    if company:
+        co = _request("POST", "objects/companies/records/query", json={
+            "filter": {"name": {"$eq": company}}, "limit": 1,
+        }).get("data", [])
+        if co:
+            values["company"] = [{"target_object": "companies", "target_record_id": co[0]["id"]["record_id"]}]
+        else:
+            print(f"WARN: company '{company}' not found")
+
+    if not values:
+        print("Nothing to update")
+        return
+    result = _request("PATCH", f"objects/people/records/{record_id}", json={"data": {"values": values}})
+    _out(result.get("data", {}))
+
+
 @app.command("delete-person")
 def delete_person(record_id: str = typer.Argument(..., help="Record ID")):
     """Delete a contact."""
@@ -183,6 +226,29 @@ def add_company(
     _out(result.get("data", {}))
 
 
+@app.command("update-company")
+def update_company(
+    record_id: str = typer.Argument(..., help="Record ID"),
+    name: Optional[str] = typer.Option(None, "--name", "-n"),
+    domain: Optional[str] = typer.Option(None, "--domain", "-d"),
+    description: Optional[str] = typer.Option(None, "--desc"),
+):
+    """Update a company. Domains is replaced."""
+    values = {}
+    if name:
+        values["name"] = [{"value": name}]
+    if domain:
+        values["domains"] = [{"domain": domain}]
+    if description:
+        values["description"] = [{"value": description}]
+
+    if not values:
+        print("Nothing to update")
+        return
+    result = _request("PATCH", f"objects/companies/records/{record_id}", json={"data": {"values": values}})
+    _out(result.get("data", {}))
+
+
 @app.command("delete-company")
 def delete_company(record_id: str = typer.Argument(..., help="Record ID")):
     """Delete a company."""

{oto_cli-1.3.0 → oto_cli-1.4.0}/oto/commands/browser.py

@@ -208,6 +208,83 @@ def linkedin_messages(
     print(json.dumps(result, indent=2, ensure_ascii=False))
 
 
+@linkedin_app.command("login")
+def linkedin_login(
+    profile: str = typer.Option(..., help="Chrome profile directory to provision/refresh (e.g. ~/.config/browser/linkedin)"),
+    channel: Optional[str] = typer.Option(None, envvar="BROWSER_CHANNEL", help="Chrome channel"),
+):
+    """Open a headed browser to log into LinkedIn; the session persists in <profile>.
+
+    Run once per profile. Cookie injection is blocked by LinkedIn's TLS
+    fingerprinting — a session created inside this same browser is the only
+    reliable way to authenticate scraping/outreach afterwards.
+    """
+    import asyncio
+    import json
+    import sys
+    from o_browser import BrowserClient
+
+    async def run():
+        async with BrowserClient(profile_path=profile, interactive=True, channel=channel) as browser:
+            await browser.goto("https://www.linkedin.com/login")
+            print(
+                "→ Log into LinkedIn in the opened window, then CLOSE it to save the session.",
+                file=sys.stderr,
+            )
+            await browser.wait_closed()
+        return {"status": "session_saved", "profile": profile}
+
+    print(json.dumps(asyncio.run(run()), indent=2, ensure_ascii=False))
+
+
+@linkedin_app.command("send")
+def linkedin_send(
+    url: str = typer.Argument(..., help="Recipient profile URL (must be a 1st-degree connection)"),
+    message: str = typer.Argument(..., help="Message body"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Type the message but do NOT click send (saves a screenshot)"),
+    cookie: Optional[str] = typer.Option(None, envvar="LINKEDIN_COOKIE", help="li_at cookie"),
+    cdp_url: Optional[str] = typer.Option(None, "--cdp-url", help="Connect to existing Chrome via CDP"),
+    identity: str = typer.Option("default", help="Identity for rate limiting"),
+    profile: Optional[str] = typer.Option(None, help="Chrome profile directory path"),
+    channel: Optional[str] = typer.Option(None, envvar="BROWSER_CHANNEL", help="Chrome channel"),
+    no_rate_limit: bool = typer.Option(False, "--no-rate-limit", help="Disable rate limiting"),
+    headless: bool = typer.Option(True, help="Run headless"),
+):
+    """Send a direct message to a 1st-degree connection."""
+    import asyncio
+    import json
+
+    async def run():
+        async with _linkedin_client(cookie=cookie, cdp_url=cdp_url, identity=identity, profile=profile, channel=channel, headless=headless, rate_limit=not no_rate_limit) as client:
+            return await client.send_message(url, message, dry_run=dry_run)
+
+    print(json.dumps(asyncio.run(run()), indent=2, ensure_ascii=False))
+
+
+@linkedin_app.command("connect")
+def linkedin_connect(
+    url: str = typer.Argument(..., help="Profile URL to send a connection request to"),
+    note: Optional[str] = typer.Option(None, "--note", help="Optional note (<=300 chars)"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Open the invite dialog but do NOT click send (saves a screenshot)"),
+    cookie: Optional[str] = typer.Option(None, envvar="LINKEDIN_COOKIE", help="li_at cookie"),
+    cdp_url: Optional[str] = typer.Option(None, "--cdp-url", help="Connect to existing Chrome via CDP"),
+    identity: str = typer.Option("default", help="Identity for rate limiting"),
+    profile: Optional[str] = typer.Option(None, help="Chrome profile directory path"),
+    channel: Optional[str] = typer.Option(None, envvar="BROWSER_CHANNEL", help="Chrome channel"),
+    no_rate_limit: bool = typer.Option(False, "--no-rate-limit", help="Disable rate limiting"),
+    headless: bool = typer.Option(True, help="Run headless"),
+):
+    """Send a connection invitation (cold-outreach primitive), optionally with a note."""
+    import asyncio
+    import json
+
+    async def run():
+        async with _linkedin_client(cookie=cookie, cdp_url=cdp_url, identity=identity, profile=profile, channel=channel, headless=headless, rate_limit=not no_rate_limit) as client:
+            return await client.send_invitation(url, note=note, dry_run=dry_run)
+
+    print(json.dumps(asyncio.run(run()), indent=2, ensure_ascii=False))
+
+
 @app.command("google")
 def google_search(
     query: str = typer.Option(..., "--query", "-q", help="Search query"),

{oto_cli-1.3.0 → oto_cli-1.4.0}/oto/commands/config.py

@@ -21,6 +21,7 @@ TRACKED_SECRETS = [
     "FOLK_API_KEY",
     "ATTIO_API_KEY",
     "TULS_API_TOKEN",
+    "OTO_API_KEY",
 ]
 
 

oto_cli-1.4.0/oto/commands/culture.py

@@ -0,0 +1,107 @@
+"""Culture (Ministère de la Culture open data) commands.
+
+Sub-namespaces by dataset:
+- spectacle: Licences entrepreneurs de spectacles vivants (LES)
+
+Future: festivals, cnc, adsv, …
+"""
+
+import json
+import typer
+from typing import Optional
+
+app = typer.Typer(help="French Ministry of Culture open data (data.culture.gouv.fr)")
+
+# spectacle sub-namespace
+spectacle_app = typer.Typer(help="Licences entrepreneurs de spectacles vivants (LES)")
+app.add_typer(spectacle_app, name="spectacle")
+
+
+def _print(obj):
+    print(json.dumps(obj, indent=2, ensure_ascii=False, default=str))
+
+
+@spectacle_app.command("search")
+def spectacle_search(
+    status: str = typer.Option("Valide", "--status", help="Valide|Invalide|Expiré|Invalidé|En instruction (case-sensitive)"),
+    categorie: Optional[str] = typer.Option(None, "--categorie", "-c", help="1 (lieu), 2 (producteur), 3 (diffuseur)"),
+    naf: Optional[str] = typer.Option(None, "--naf", help="NAF prefix (e.g. 90.01Z or 9001Z) — handles unnormalized field"),
+    region: Optional[str] = typer.Option(None, "--region", help="Région SIRET (e.g. 'Île-de-France')"),
+    dept: Optional[str] = typer.Option(None, "--dept", help="Département SIRET (e.g. 'Paris', 'Bouches-du-Rhône')"),
+    cp: Optional[str] = typer.Option(None, "--cp", help="Code postal SIRET"),
+    siren: Optional[str] = typer.Option(None, "--siren", help="SIREN (9) or SIRET (14) prefix — matches all records starting with it"),
+    declarant: Optional[str] = typer.Option(None, "--declarant", help="Substring match on type_declarant (e.g. 'privé', 'association', 'public')"),
+    since: Optional[str] = typer.Option(None, "--since", help="Filed since YYYY-MM-DD"),
+    raw_where: Optional[str] = typer.Option(None, "--where", help="Raw Opendatasoft where clause (advanced)"),
+    order: str = typer.Option("date_depot_dossier desc", "--order", help="order_by clause"),
+    limit: int = typer.Option(20, "--limit", "-n", help="Max results (1-100 per page)"),
+    offset: int = typer.Option(0, "--offset", help="Pagination offset"),
+):
+    """Search LES with composed AND filters (statut + catégorie + NAF + région…)."""
+    from oto.tools.culture import SpectacleClient
+    client = SpectacleClient()
+    try:
+        result = client.search(
+            status=status, categorie=categorie, naf=naf, region=region,
+            departement=dept, code_postal=cp, siren=siren,
+            type_declarant_like=declarant, deposited_since=since,
+            raw_where=raw_where, order_by=order, limit=limit, offset=offset,
+        )
+    except ValueError as e:
+        raise typer.BadParameter(str(e))
+    _print(result)
+
+
+@spectacle_app.command("get")
+def spectacle_get(
+    siren: str = typer.Argument(..., help="SIREN (9) or SIRET (14) — returns all récépissés for that entity"),
+):
+    """Fetch all récépissés (L1/L2/L3) for a SIREN/SIRET."""
+    from oto.tools.culture import SpectacleClient
+    client = SpectacleClient()
+    _print(client.get(siren))
+
+
+@spectacle_app.command("stats")
+def spectacle_stats(
+    by: str = typer.Argument(..., help="Field to group on: code_naf_ape|region_siret|departement_siret|categorie|type_declarant"),
+    status: str = typer.Option("Valide", "--status"),
+    categorie: Optional[str] = typer.Option(None, "--categorie", "-c"),
+    naf: Optional[str] = typer.Option(None, "--naf"),
+    region: Optional[str] = typer.Option(None, "--region"),
+    dept: Optional[str] = typer.Option(None, "--dept"),
+    limit: int = typer.Option(20, "--limit", "-n"),
+):
+    """Group-by aggregate (fills the gap of the official datagouv MCP)."""
+    from oto.tools.culture import SpectacleClient
+    client = SpectacleClient()
+    try:
+        result = client.stats(
+            by,
+            where_filters={
+                "status": status, "categorie": categorie, "naf": naf,
+                "region": region, "departement": dept,
+            },
+            limit=limit,
+        )
+    except ValueError as e:
+        raise typer.BadParameter(str(e))
+    _print(result)
+
+
+@spectacle_app.command("export-url")
+def spectacle_export_url(
+    fmt: str = typer.Option("csv", "--format", "-f", help="csv|json|parquet|xlsx"),
+    status: Optional[str] = typer.Option("Valide", "--status"),
+    categorie: Optional[str] = typer.Option(None, "--categorie", "-c"),
+    naf: Optional[str] = typer.Option(None, "--naf"),
+    region: Optional[str] = typer.Option(None, "--region"),
+    dept: Optional[str] = typer.Option(None, "--dept"),
+):
+    """Build a direct export URL — caller streams it (~6 MB CSV for full valid set)."""
+    from oto.tools.culture import SpectacleClient
+    client = SpectacleClient()
+    print(client.export_url(
+        fmt=fmt, status=status, categorie=categorie, naf=naf,
+        region=region, departement=dept,
+    ))