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

# Command reference

> Every engini command, its options, and examples.

All commands also accept the universal flags (`--json`, `--quiet`, `--schema`, and `--dry-run` on mutating commands) - see the [overview](/cli/overview).

## Account

### `engini login`

Store an Engini API key.

| Option                 | Meaning                                           |
| ---------------------- | ------------------------------------------------- |
| `--api-key <key>`      | Opaque Engini key (`eng_…`) - non-interactive     |
| `--api-url <url>`      | API base URL to persist (e.g. a staging host)     |
| `--identity-url <url>` | Dashboard base URL (hosts the keys page)          |
| `--force`              | Overwrite existing credentials without confirming |

```bash theme={null}
engini login --api-key eng_…                       # store a key non-interactively
engini login --api-url https://staging.engini.io   # point at another environment
engini login --api-key eng_… --dry-run             # preview without writing
```

On a TTY without `--api-key`, the CLI offers to open the key-creation page and prompts for the key (hidden input). Non-interactive without `--api-key` exits `2`.

### `engini logout`

Clear the stored credentials. Prints `{"logged_out": true}` (or `"noop": true` when nothing was stored).

### `engini whoami`

Report the authenticated identity: `full_name`, `email`, `current_company`, `role`, `user_type` (`apiuser` for an API key, `user` for a JWT).

```bash theme={null}
engini whoami --json | jq -r '.email'
```

## Tools

### `engini tools list`

| Option                 | Meaning                                                                      |
| ---------------------- | ---------------------------------------------------------------------------- |
| `--application <slug>` | Filter by application slug                                                   |
| `--toolset <id>`       | List the tools of a server toolset (mutually exclusive with `--application`) |
| `--limit <n>`          | Cap the number of tools returned                                             |

```bash theme={null}
engini tools list --application monday --limit 5
engini tools list | jq -r '.[].tool_slug'
```

### `engini tools get <tool_id>`

Full canonical detail for one tool - including `input_schema`, `output_schema`, and the `supports_filters` / `supports_sort` / `supports_top_offset` capability flags.

```bash theme={null}
engini tools get monday_create_item --json
```

### `engini tools call <tool_id>`

Execute a tool against a connection.

| Option                | Meaning                                                                   |
| --------------------- | ------------------------------------------------------------------------- |
| `--args <args>`       | **Required.** JSON object, `@file.json`, or `-` for stdin                 |
| `--file <spec>`       | Attach a file: `field=@path` (repeat the field for a list)                |
| `--connection <id>`   | Connection id to run against                                              |
| `--toolset <id>`      | Toolset id to resolve the connection                                      |
| `--raw`               | Emit the tool output verbatim (no envelope)                               |
| `--llm <vendor>`      | Provider-shaped result: `openai` \| `anthropic`                           |
| `--tool-call-id <id>` | Correlation id for `--llm` output                                         |
| `--max-bytes <n>`     | Spill results larger than N bytes to a handle (default 4096; `0` = never) |
| `--inline`            | Force the full inline result                                              |

```bash theme={null}
engini tools call monday_create_item --args '{}' --dry-run
engini tools call monday_create_item --args @item.json --connection 3
echo '{"name":"x"}' | engini tools call monday_create_item --args -
engini tools call gmail_send_mail --args '{}' --file attachmentsarray=@report.pdf
engini tools call monday_create_item --args '{}' --llm openai --tool-call-id call_1
```

Connection precedence: `--connection` > `--toolset` > the application's default. Default output envelope: `{output, history_id, execution_info}`; results larger than `--max-bytes` are stored locally and replaced by a **handle**.

### `engini tools result [handle]`

Drill into a stored (sandboxed) result.

| Option                         | Meaning                                                               |
| ------------------------------ | --------------------------------------------------------------------- |
| `--select <path>`              | Dot-path to extract, e.g. `items.email` (repeatable; maps over lists) |
| `--fields <keys>`              | Comma-separated keys to project from object(s)                        |
| `--offset <n>` / `--limit <m>` | Page a list value                                                     |
| `--full`                       | Emit the entire stored payload                                        |
| `--list`                       | List stored handles                                                   |
| `--clear`                      | Delete all stored results                                             |

```bash theme={null}
engini tools result h42                          # shape + preview
engini tools result h42 --select items.email     # one dot-path (maps over a list)
engini tools result h42 --fields id,name         # project keys per item
engini tools result h42 --select items --offset 20 --limit 10
```

## Applications

### `engini applications list`

`--search <query>`, `--available` (only apps you can use), `--limit <n>`.

```bash theme={null}
engini applications list --available --limit 10
engini applications list --search crm --json
```

### `engini applications get <slug>`

Adds `supports_object_selection`, `help_url`, and `authentication_methods` - how you discover `--auth <id>` and credential field names for connecting.

## Connect

### `engini connect [<app>]`

The guided way to create a connection - interactive on a TTY, **agent-resumable** when piped (see the [machine contract](/cli/machine-contract)).

| Option                                              | Meaning                                            |
| --------------------------------------------------- | -------------------------------------------------- |
| `--auth <id>`                                       | Authentication method id                           |
| `--name <name>`                                     | Connection name                                    |
| `--field <spec>`                                    | Credential field `key=value` (repeatable)          |
| `--object <id>`                                     | Object id to select (repeatable)                   |
| `--no-objects`                                      | Skip object selection                              |
| `--oauth-state <state>`                             | Resume an OAuth2 sign-in by its state token        |
| `--connection <id>`                                 | Resume object selection for an existing connection |
| `--no-wait`                                         | Return early instead of waiting for async jobs     |
| `--timeout <seconds>` / `--poll-interval <seconds>` | Polling controls (defaults 300 / 2)                |

```bash theme={null}
engini connect                       # open the web connections page
engini connect monday                # interactive walkthrough (TTY)
engini connect monday --field ApiKey=… --name 'My Monday'
engini connect monday --json         # agent: prints the next step + exit 5
engini connect outlook --oauth-state <state>      # resume an OAuth sign-in
engini connect monday --connection 42 --object 5  # resume object selection
```

Flow: discover auth methods → collect credentials (or run OAuth) → create → check → refresh objects → select objects → `{"connection_id", "is_alive", "objects_selected"}`.

## Connections

### `engini connections list | get`

```bash theme={null}
engini connections list --application monday
engini connections get 42 --json
```

Credential `fields` and `metadata` are deliberately omitted from `get` - they can carry secrets.

### `engini connections create <application>`

Direct-credential connections (`--auth <id>`, `--name <name>`, repeatable `--field key=value`). OAuth2 apps use `engini connect` instead.

```bash theme={null}
engini connections create slack --auth 2 --name Sales --field token=xoxb-1
```

### `engini connections delete <connection_id>`

Prompts on a TTY; requires `--force` non-interactively.

### `engini connections check <connection_id>`

Liveness test. A conclusive failure exits `1`; an inconclusive check reports `is_alive: null` and exits `0`.

### `engini connections refresh <connection_id>`

Async object refresh - waits by default (`--no-wait` to return immediately, `--timeout` default 300s). A failed refresh exits `1`; a timeout exits `124`.

### `engini connections objects | select-objects <connection_id>`

```bash theme={null}
engini connections objects 42 --name leads
engini connections select-objects 42 --object 5 --object 9
```

### `engini connections sign-in-url | oauth-complete <application>`

The OAuth primitives behind `connect`:

```bash theme={null}
engini connections sign-in-url outlook --auth 0
# -> {"sign_in_url": …, "state": …, "resume": "engini connections oauth-complete outlook --auth 0 --state <state>"}
engini connections oauth-complete outlook --auth 0 --state <state>
```