CLI reference
=============

The ``gseai`` command-line tool lets you interact with the server without writing
any Python.

Authentication
--------------

Every command requires a bearer token. Set it once as an environment variable so
you don't have to type it on every call:

.. code-block:: bash

   export GSEAI_API_TOKEN=your-api-token

You can also pass it inline with ``-t`` / ``--token``.

Global options
--------------

These options apply to every command and must come *before* the subcommand.

.. code-block:: text

   gseai [OPTIONS] COMMAND [ARGS]...

.. list-table::
   :header-rows: 1
   :widths: 20 15 50

   * - Flag
     - Env var
     - Description
   * - ``-t``, ``--token``
     - ``GSEAI_API_TOKEN``
     - Bearer auth token (required)
   * - ``-H``, ``--host``
     - ``GSEAI_HOST``
     - Server hostname (default: ``gseai.gse.buffalo.edu``)
   * - ``-p``, ``--port``
     - ``GSEAI_PORT``
     - Server port (default: ``11434``)
   * - ``-T``, ``--timeout``
     - ``GSEAI_TIMEOUT``
     - Request timeout in seconds (default: no timeout)

Models
------

.. code-block:: bash

   gseai models          # one model ID per line
   gseai models -j       # raw JSON

Chat
----

Single-turn chat with a plain-text prompt:

.. code-block:: bash

   gseai chat gemma-4-e2b-it "What is machine learning?"

   # Read the prompt from a file
   gseai chat gemma-4-e2b-it -f prompt.txt

   # Interactive session (multi-turn, retains conversation history)
   gseai chat gemma-4-e2b-it -i

   # Interactive with a system prompt and streaming
   gseai chat gemma-4-e2b-it -i -s "You are a concise tutor." -S

Type ``exit`` or press ``Ctrl+C`` to end an interactive session.

.. list-table::
   :header-rows: 1
   :widths: 20 60

   * - Flag
     - Description
   * - ``-f``, ``--file``
     - Read the prompt from a file
   * - ``-i``, ``--interactive``
     - Start a multi-turn chat session, retaining conversation history
   * - ``-s``, ``--system``
     - System prompt
   * - ``-t``, ``--temperature``
     - Sampling temperature (0–2)
   * - ``-m``, ``--max-tokens``
     - Maximum tokens to generate per turn
   * - ``-S``, ``--stream``
     - Stream tokens as they arrive
   * - ``-j``, ``--json``
     - Print full JSON response (single-turn only)

Completions
-----------

Legacy text completion (no chat structure):

.. code-block:: bash

   gseai completions gemma-4-e2b-it "Once upon a time"

Accepts the same ``-t``, ``-m``, ``-S``, ``-j`` flags as ``chat``.

Embeddings
----------

.. code-block:: bash

   gseai embeddings nomic-embed-text "Hello world"
   # model:      nomic-embed-text
   # dimensions: 768
   # values:     [0.0142, -0.0317, ...]

   gseai embeddings nomic-embed-text "Hello world" -j   # full JSON

Audio
-----

transcribe
^^^^^^^^^^

Transcribe an audio file to text using Whisper:

.. code-block:: bash

   gseai audio transcribe whisper recording.mp3
   gseai audio transcribe whisper lecture.mp3 -l fr   # French source
   gseai audio transcribe whisper lecture.mp3 -f srt  # SRT subtitles

.. list-table::
   :header-rows: 1
   :widths: 20 60

   * - Flag
     - Description
   * - ``-l``, ``--language``
     - Source language code (e.g. ``en``, ``fr``); auto-detected if omitted
   * - ``-p``, ``--prompt``
     - Context hint passed to the model
   * - ``-f``, ``--format``
     - Response format: ``text`` (default), ``json``, ``verbose_json``, ``srt``, ``vtt``
   * - ``-j``, ``--json``
     - Print full JSON (equivalent to ``--format verbose_json``)

translate
^^^^^^^^^

Transcribe and translate to English in one step:

.. code-block:: bash

   gseai audio translate whisper french_lecture.mp3

Accepts the same ``-p``, ``-f``, ``-j`` flags as ``transcribe``.

speech
^^^^^^

Synthesize speech from text (requires a TTS model):

.. code-block:: bash

   gseai audio speech tts-model "Hello, world" -o hello.mp3

.. list-table::
   :header-rows: 1
   :widths: 20 60

   * - Flag
     - Description
   * - ``-o``, ``--output``
     - Output file path (default: ``speech.mp3``)
   * - ``-v``, ``--voice``
     - Voice identifier
   * - ``-s``, ``--speed``
     - Playback speed (default: ``1.0``)

Images
------

generate
^^^^^^^^

Generate an image from a text prompt:

.. code-block:: bash

   gseai images generate stable-diffusion "a red barn in a snowy field"
   gseai images generate stable-diffusion "a red barn" -o barn.png -n 3

When ``--n`` is greater than 1 the output filenames are numbered:
``barn_1.png``, ``barn_2.png``, etc.

.. list-table::
   :header-rows: 1
   :widths: 20 60

   * - Flag
     - Description
   * - ``-o``, ``--output``
     - Output file path (default: ``image.png``)
   * - ``-n``, ``--n``
     - Number of images to generate (default: ``1``)
   * - ``-s``, ``--size``
     - Image dimensions, e.g. ``512x512``
   * - ``-S``, ``--steps``
     - Diffusion steps
   * - ``-r``, ``--seed``
     - Random seed for reproducibility
   * - ``-j``, ``--json``
     - Print raw JSON response

edit
^^^^

Edit an existing image guided by a text prompt:

.. code-block:: bash

   gseai images edit stable-diffusion photo.png "replace the sky with a sunset"
   gseai images edit stable-diffusion photo.png "repaint the sky" -m mask.png

.. list-table::
   :header-rows: 1
   :widths: 20 60

   * - Flag
     - Description
   * - ``-m``, ``--mask``
     - Greyscale mask image (white = area to edit)
   * - ``-o``, ``--output``
     - Output file path (default: ``edited.png``)
   * - ``-n``, ``--n``
     - Number of variants
   * - ``-s``, ``--size``
     - Output dimensions
   * - ``-j``, ``--json``
     - Print raw JSON response

variation
^^^^^^^^^

Generate variations of an existing image:

.. code-block:: bash

   gseai images variation stable-diffusion photo.png -n 3

.. list-table::
   :header-rows: 1
   :widths: 20 60

   * - Flag
     - Description
   * - ``-o``, ``--output``
     - Output file path (default: ``variation.png``)
   * - ``-n``, ``--n``
     - Number of variations (default: ``1``)
   * - ``-s``, ``--size``
     - Output dimensions
   * - ``-j``, ``--json``
     - Print raw JSON response