> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jinba.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install the Jinba CLI and operate Jinba Flow from your terminal

## Overview

The Jinba CLI (`jinba`) is the official command-line interface for Jinba. It lets you call the Jinba Flow API from your terminal — list workspaces, create and update flows, upload files, and more — without writing HTTP requests by hand.

## Installation

### Requirements

* Node.js 20 or later

### Install

The CLI is published to npm as a public package. Install it globally:

```bash theme={null}
npm install -g @jinba/cli
```

### Verify the installation

```bash theme={null}
jinba --version
jinba --help
```

### Update

```bash theme={null}
npm install -g @jinba/cli@latest
```

When a newer version is available, the CLI also prints an update notice in interactive terminal sessions. Older versions may eventually stop being supported; in that case the API asks you to upgrade with the same command.

## Authentication

Most API commands require a Jinba user API key. Run any API command and the CLI will prompt for the key if one has not been saved yet:

```bash theme={null}
jinba flow api workspace list
```

Get your key from your [profile page](https://flow.jinba.io/profile). The key is stored locally at `~/.config/jinba/config.json`. To remove the saved key:

```bash theme={null}
jinba logout
```

You can also configure the CLI via environment variables — useful in CI:

| Variable                         | Purpose                                 |
| -------------------------------- | --------------------------------------- |
| `JINBAFLOW_API_KEY`              | API key to use instead of the saved one |
| `JINBAFLOW_API_BASE_URL`         | Override the API base URL               |
| `JINBAFLOW_DISABLE_UPDATE_CHECK` | Disable the update notice               |

## Usage

Commands follow this pattern:

```bash theme={null}
jinba flow api <resource> <action> [options]
```

Examples:

```bash theme={null}
jinba flow api workspace list
jinba flow api flow create --workspace-id ws_123 --name "My Flow" --description "Example description"
jinba flow api flow create --workspace-id ws_123 --stdin < payload.json
jinba flow api workspace archive --workspace-id ws_123 --dry-run
jinba flow api file upload --workspace-id ws_123 --file ./report.pdf
```

Every command includes help:

```bash theme={null}
jinba flow api flow create --help
```

## Notes

* Path parameters can be passed as positional arguments or as flags such as `--workspace-id`.
* `--stdin` reads a JSON object and merges it with explicit flags.
* Mutating commands support `--dry-run` and automatically send an `Idempotency-Key`.
* Destructive commands (archive, delete, revoke, etc.) prompt for confirmation by default; pass `--yes` or `--force` to skip it.
* File upload commands accept a local file path (e.g. `--file ./report.pdf`); the CLI infers the content type from the extension.