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

# Chift CLI

> Use the Chift CLI to discover and call Chift API endpoints from a terminal or coding agent

## Command-line access to Chift

Use the Chift CLI to discover Chift API operations, inspect required inputs, and call Unified API endpoints with structured output from your terminal or coding agent.

Chift's API is organized around consumers, connections, integrations, and Unified APIs such as accounting, POS, ecommerce, invoicing, banking, payment, and PMS. The CLI keeps those concepts close to the terminal. Most API commands follow the same grouped structure as the API reference and use the `consumer_id` as the route context for endpoints that act on a specific consumer.

<CardGroup cols={2}>
  <Card title="Agent-friendly execution" icon="robot">
    Return structured JSON or YAML and keep responses focused for smaller AI context.
  </Card>

  <Card title="Open source" icon="github" href="https://github.com/chift-oneapi/chift-cli">
    View the source, report issues, or contribute on GitHub.
  </Card>
</CardGroup>

## Installation

<Steps>
  <Step title="Install the CLI">
    Download and install the latest release with a single command.

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/chift-oneapi/chift-cli/master/install.sh | sh
    ```
  </Step>

  <Step title="Configure authentication">
    Save your Chift account ID, client ID, and client secret once. The CLI validates the credentials by fetching an access token. Missing values open an interactive terminal form.

    ```bash theme={null}
    chift auth setup
    chift auth check
    ```

    You can also pass credentials directly for non-interactive use:

    ```bash theme={null}
    chift auth setup \
      --account-id <account_id> \
      --client-id <client_id> \
      --client-secret <client_secret>
    ```
  </Step>

  <Step title="First use">
    On first use the CLI fetches and caches the OpenAPI schema automatically. Browse available commands, search for an operation, or use `--next` at any level to see what to do next.

    ```bash theme={null}
    chift --help
    chift accounting --help
    chift schema search supplier
    chift accounting suppliers --next
    ```
  </Step>
</Steps>

To update an existing install:

```bash theme={null}
chift update
```

## Agent skill

The CLI ships with an agent skill that teaches coding agents how to drive it. Install the skill with the [`skills`](https://www.skills.sh/docs) CLI:

```bash theme={null}
npx skills add chift-oneapi/chift-cli
```

## Discovering and calling endpoints

### Inspecting endpoint inputs

Use `--schema` or `--next` to see the merged input schema before calling an endpoint. The CLI rejects unknown parameters before sending any request.

```bash theme={null}
chift accounting suppliers get --schema
chift accounting suppliers get --next
```

### Passing inputs

`consumer_id` is route context. Set it once via environment variable or pass it as the first positional argument:

```bash theme={null}
export CHIFT_CONSUMER_ID=<consumer_id>
chift accounting folders list

# or inline:
chift accounting folders list <consumer_id>
```

Pass other path and query parameters as `KEY=VALUE` positional values or with `--param`:

```bash theme={null}
chift accounting suppliers get <consumer_id> supplier_id=<supplier_id>

chift accounting suppliers get <consumer_id> \
  --param supplier_id=<supplier_id> \
  --param folder_id=<folder_id>
```

### Posting data

For `POST` and `PATCH` operations, pass a JSON body with `--json` or use `KEY=VALUE` pairs. Mutating operations require `--force`.

```bash theme={null}
chift accounting suppliers create <consumer_id> \
  --force \
  name="Acme Corp" \
  currency_code=EUR

chift accounting suppliers create <consumer_id> \
  --force \
  --json '{"name": "Acme Corp", "currency_code": "EUR"}'
```

### Output and filtering

API commands return JSON by default. Use `--output yaml` for YAML, or `--debug` to write debug logs to stderr.

```bash theme={null}
chift accounting folders list <consumer_id> --fields id,name,parent.id
chift accounting suppliers list <consumer_id> --filter name=Acme
chift accounting suppliers list <consumer_id> page=2 size=50
```

`--fields` keeps only selected fields from the response. `--filter` filters list responses client-side. For paginated responses, the CLI applies both to the `items` array. Pagination uses the API's own `page` and `size` query parameters.

## Environment variables

The CLI loads environment variables at startup from a `.env` file or shell exports.

| Variable                        | Description                                                                              | Default |
| ------------------------------- | ---------------------------------------------------------------------------------------- | ------- |
| `CHIFT_CONSUMER_ID`             | Default consumer, avoids passing `consumer_id` on every command                          | —       |
| `CHIFT_ALLOWED_OPERATIONS`      | Comma-separated list of allowed operation classes: `read`, `write`, `dangerous`, `all`   | all     |
| `CHIFT_SHOW_PLATFORM_ENDPOINTS` | Show `consumers`, `integrations`, and `connections` endpoint groups                      | `false` |
| `CHIFT_SHOW_INTERNAL_ENDPOINTS` | Show `general`, `datastores`, `syncs`, `issues`, `m-c-p`, and `webhooks` endpoint groups | `false` |

### Restricting operations

Set `CHIFT_ALLOWED_OPERATIONS` to limit which operation classes the CLI executes for business vertical endpoints. This is particularly useful for AI agents that should only read data.

```bash theme={null}
CHIFT_ALLOWED_OPERATIONS=read chift accounting suppliers list <consumer_id>
```

Scope metadata takes precedence when present. Without scopes, `GET`/`HEAD`/`OPTIONS` are `read`, `POST`/`PATCH` are `write`, and `DELETE` is `dangerous`. Platform and internal endpoint groups keep their full command set regardless of this setting.

## Schema cache

The command tree is generated from the OpenAPI schema. The CLI fetches and caches the schema automatically on first use. Refresh it manually when needed:

```bash theme={null}
chift schema update
chift schema tree
chift schema search invoice
```

## Why it helps AI workflows

AI coding tools work best when they can discover capabilities, inspect schemas, and receive compact structured output. The Chift CLI supports that workflow by:

* Discovering available Chift API operations from the terminal
* Guiding agents step-by-step with `--next` at any command level
* Inspecting the inputs required by an endpoint before sending a request
* Returning JSON by default, with YAML available when needed
* Reducing large responses with `--fields` and `--filter`
* Restricting operations with `CHIFT_ALLOWED_OPERATIONS` so agents only perform safe actions
* Requiring `--force` for mutating operations such as `POST`, `PATCH`, `PUT`, and `DELETE`

<Tip>
  For AI agents, start with `chift auth check`, use `chift schema search` or
  `--help` to discover the right endpoint, then call `--schema` before sending
  business data. Set `CHIFT_ALLOWED_OPERATIONS=read` to prevent accidental writes.
</Tip>

## Relationship with MCP

The [Chift MCP server](/ai/mcp) is the recommended option when your AI tool supports MCP and should access Chift through a tool interface. The CLI is a strong complement for terminal-based agents, local scripts, CI checks, and debugging sessions. Use it whenever you want to see the exact API request and response shape.