✨ add support for V2 CLI (#200)

Author: sebastianMindee

.github/workflows/_publish-docs.yml

@@ -14,7 +14,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Set up php ${{ matrix.php-version }}
+      - name: Set up php 8.3
         uses: shivammathur/setup-php@v2
         with:
           php-version: 8.3
@@ -30,7 +30,7 @@ jobs:
           cp -r ./docs/code_samples ./docs/_build/
 
       - name: Deploy
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./docs/_build

.github/workflows/_static-analysis.yml

@@ -20,7 +20,7 @@ jobs:
         tools: composer
 
     - name: Cache dependencies
-      uses: actions/cache@v3
+      uses: actions/cache@v5
       with:
         path: ./vendor
         key: ${{ runner.os }}-${{ hashFiles('composer.json') }}

.github/workflows/_test-cli.yml

@@ -0,0 +1,46 @@
+name: Test Command Line Interface
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+env:
+  MINDEE_API_KEY: ${{ secrets.MINDEE_API_KEY_SE_TESTS }}
+  MINDEE_V2_API_KEY: ${{ secrets.MINDEE_V2_SE_TESTS_API_KEY }}
+  MINDEE_V2_SE_TESTS_FINDOC_MODEL_ID: ${{ secrets.MINDEE_V2_SE_TESTS_FINDOC_MODEL_ID }}
+  MINDEE_V2_SE_TESTS_CLASSIFICATION_MODEL_ID: ${{ secrets.MINDEE_V2_SE_TESTS_CLASSIFICATION_MODEL_ID }}
+  MINDEE_V2_SE_TESTS_CROP_MODEL_ID: ${{ secrets.MINDEE_V2_SE_TESTS_CROP_MODEL_ID }}
+  MINDEE_V2_SE_TESTS_SPLIT_MODEL_ID: ${{ secrets.MINDEE_V2_SE_TESTS_SPLIT_MODEL_ID }}
+  MINDEE_V2_SE_TESTS_OCR_MODEL_ID: ${{ secrets.MINDEE_V2_SE_TESTS_OCR_MODEL_ID }}
+
+jobs:
+  test:
+    name: Run CLI Tests
+    timeout-minutes: 30
+    strategy:
+      max-parallel: 2
+      matrix:
+        php-version:
+          - "8.1"
+          - "8.5"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set up PHP ${{ matrix.php-version }}
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-version }}
+      - uses: ramsey/composer-install@v3
+
+      - name: Test V2 CLI
+        shell: sh
+        run: |
+          ./tests/test_v2_cli.sh ./tests/resources/file_types/pdf/blank_1.pdf
+
+      - name: Test V1 CLI
+        shell: sh
+        run: |
+          ./tests/test_v1_cli.sh ./tests/resources/file_types/pdf/blank_1.pdf

.github/workflows/_workflow_lint.yml

@@ -0,0 +1,20 @@
+name: Lint workflows
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  actionlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Download actionlint
+        id: get_actionlint
+        run: bash <(curl https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
+        shell: bash
+      - name: Run actionlint
+        run: ${{ steps.get_actionlint.outputs.executable }} -color
+        shell: bash

.github/workflows/cron.yml

@@ -8,3 +8,6 @@ jobs:
   smoke-test:
     uses: mindee/mindee-api-php/.github/workflows/_test-smoke.yml@main
     secrets: inherit
+  test-cli:
+    uses: mindee/mindee-api-php/.github/workflows/_test-cli.yml@main
+    secrets: inherit

.github/workflows/pull-request.yml

@@ -8,8 +8,11 @@ permissions:
   pull-requests: read
 
 jobs:
+  workflow-lint:
+    uses: ./.github/workflows/_workflow_lint.yml
   static-analysis:
     uses: ./.github/workflows/_static-analysis.yml
+    needs: workflow-lint
   static-dependency-checks:
     uses: ./.github/workflows/_static-dependency-checks.yml
     needs: static-analysis
@@ -25,3 +28,7 @@ jobs:
     uses: ./.github/workflows/_test-smoke.yml
     needs: test-units
     secrets: inherit
+  test-cli:
+    uses: ./.github/workflows/_test-cli.yml
+    needs: test-units
+    secrets: inherit

CHANGELOG.md

@@ -1,5 +1,6 @@
 # Mindee PHP API Library Changelog
 
+
 ## v3.0.0-rc1 - 2026-06-10
 ### Changes
 * :recycle: move page count to attribute

CLI.md

@@ -2,56 +2,105 @@
 
 The CLI tool is provided mainly for quick tests and debugging.
 
+The CLI ships **two top-level groups**:
+
+* V2 product subcommands at the root: `extraction`, `classification`,
+  `crop`, `ocr`, `split`, plus `search-models`.
+* All V1 products live under a `v1` group (e.g. `mindee v1 invoice ...`).
+
+For backward compatibility, invoking a V1 product name directly
+(`mindee invoice ...`, `mindee receipt ...`, …) is automatically
+dispatched to `mindee v1 <product> ...`.
+
 ### General help
 
 ```shell
-./mindee generated --help
+./mindee --help
+./mindee v1 --help
+./mindee extraction --help
+./mindee search-models --help
 ```
 
 > Note: Due to the limited-nature of most PHP CLI tools, the help sections aren't customized for each command.
 
+## V1 commands
+
 ### Example parse command for Off-the-Shelf document
 
 ```shell
-./mindee invoice -k xxxxxxx /path/to/invoice.pdf
+./mindee v1 invoice -k xxxxxxx /path/to/invoice.pdf
 ```
 
+> Legacy `./mindee invoice -k xxxxxxx /path/to/invoice.pdf` still works.
+
 ### Works with environment variables
 
 ```shell
 export MINDEE_API_KEY=xxxxxx
-./mindee invoice /path/to/invoice.pdf
+./mindee v1 invoice /path/to/invoice.pdf
 ```
 
 ### Example parse command for a generated document (docTI)
 
 ```shell
-./mindee generated -a pikachu -k xxxxxxx pokemon_card /path/to/card.jpg -A
+./mindee v1 generated -a pikachu -k xxxxxxx pokemon_card /path/to/card.jpg -A
 ```
 
 
 ### Example async parse command
 
 ```shell
-./mindee invoice-splitter path/to/the/invoice.pdf -A
+./mindee v1 invoice-splitter path/to/the/invoice.pdf -A
 ```
 
 > Note: the `-A` can be omitted on products which do not support synchronous mode.
 
+### Full parsed output
+
 ```shell
-./mindee invoice-splitter path/to/the/invoice.pdf -A
+./mindee v1 invoice -k xxxxxxx /path/to/invoice.pdf -o raw
 ```
 
-### [DEPRECATED] Example parse command for a custom document (API Builder)
+## V2 commands
+
+V2 inference commands share the same option set:
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--model-id` | `-m` | ID of the model to use (required). |
+| `--api-key` | `-k` | API key. Falls back to `MINDEE_V2_API_KEY`. |
+| `--alias` | `-a` | Optional alias for the file. |
+| `--output` | `-o` | `summary` (default), `full`, or `raw`. |
+
+The `extraction` command adds:
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--rag` | `-g` | Enable Retrieval-Augmented Generation. |
+| `--raw-text` | `-r` | Extract the document's raw text. |
+| `--confidence` | `-c` | Return per-field confidence scores. |
+| `--polygon` | `-p` | Return per-field bounding polygons. |
+| `--text-context` | `-t` | Add text context to the API call. |
+
+### Example V2 extraction call
 
 ```shell
-./mindee custom -a pikachu -k xxxxxxx pokemon_card /path/to/card.jpg
+export MINDEE_V2_API_KEY=xxxxxx
+./mindee extraction -m <model-id> /path/to/file.pdf
 ```
 
-### Full parsed output
+### Example V2 extraction with options and a JSON dump
+
+```shell
+./mindee extraction -m <model-id> -k <api-key> -r -c -p -o full /path/to/file.pdf
+./mindee extraction -m <model-id> -o raw /path/to/file.pdf
+```
+
+### Listing models
 
 ```shell
-./mindee invoice -k xxxxxxx /path/to/invoice.pdf -o raw
+./mindee search-models -k <api-key>
+./mindee search-models --name fin --model-type extraction -r
 ```
 
 ### Running the script through php

bin/MindeeCliCommand.php

@@ -49,14 +49,14 @@ class MindeeCliCommand extends Command
      */
     public function __construct(array $documentList)
     {
-        require __DIR__ . '/../src/version.php';
+        require_once __DIR__ . '/../src/version.php';
         $this->documentList = $documentList;
 
         $this->acceptableDocuments = [];
         foreach ($this->documentList as $documentName => $document) {
             $this->acceptableDocuments[] = $documentName;
         }
-        parent::__construct('mindee');
+        parent::__construct('v1');
     }
 
     /**
@@ -66,9 +66,9 @@ protected function formatHelp(string $product = null): string
     {
         $helpCondensed = "";
         if (!$product) {
-            $helpCondensed = "Mindee Command-Line interface.
+            $helpCondensed = "Mindee V1 Command-Line interface.
 Usage:
-  mindee [options] [--] <product> <method> <file_path_or_url>
+  mindee v1 [options] [--] <product> <file_path_or_url>
 
 Available products:";
             foreach ($this->documentList as $documentName => $document) {
@@ -92,8 +92,8 @@ protected function formatHelp(string $product = null): string
     protected function configure(): void
     {
         $this
-            ->setName('mindee')
-            ->setDescription('Mindee client.')
+            ->setName('v1')
+            ->setDescription('Mindee V1 product commands.')
             ->addArgument(
                 'product',
                 InputArgument::REQUIRED,