@engini/cli

Machine-first command line for the Engini Public API — run tools across your connected apps from the terminal or an agent. The engini binary is a TypeScript port of the Python engini CLI, kept in lockstep with it.

Install

npm install -g @engini/cli
# or run without installing:
npx @engini/cli --help

Quickstart

engini login --api-key eng_…              # or run interactively on a TTY
engini applications list --available      # discover connector apps
engini tools list --application monday    # discover tools
engini tools call monday_create_item --args '{}' --connection 3
engini tools call gmail_send_mail --args '{}' --file [email protected]   # attach a file
engini tools result <handle> --select items.email   # drill into a large result

Commands

engini login | logout | whoami            # auth
engini tools list | get | call | result   # discover, execute & drill into results
engini applications list | get            # browse connector apps
engini connect [<app>]                    # create a connection (interactive / agent-resumable)
engini connections list | get             # inspect connections
engini connections create | delete | check | refresh | objects | select-objects   # primitives
engini connections sign-in-url | oauth-complete   # OAuth2 start / finish primitives

Run engini <command> --help for details and examples on any command.

connect <app> discovers the app's authentication methods, collects credentials (or runs the OAuth2 sign-in), creates the connection, checks it, refreshes its objects, and — when the app supports it — lets you pick which objects to sync. On a TTY it prompts and opens the browser inline. Async jobs poll up to --timeout (--no-wait returns early; a timeout exits 124).

Agent recipe (piped / non-TTY)

connect never blocks for an agent: at each gate it prints a self-describing { "need": …, "resume": "<exact next command>" } and exits 5. The agent asks the user for the value and runs the resume command:

# direct-credential (e.g. monday)
engini connect monday --json                  # → {need:"fields", resume:"engini connect monday --auth 0 --field ApiKey=<value>"}
engini connect monday --auth 0 --field ApiKey=<key>   # creates → checks → refreshes

# OAuth2 (e.g. outlook) — never opens a browser for the agent
engini connect outlook --json                 # → {need:"oauth", sign_in_url, state, resume:"engini connect outlook --oauth-state <state>"}
#   show sign_in_url to the user; after they sign in:
engini connect outlook --oauth-state <state>  # polls token → creates → checks → refreshes

# object selection (apps that support it) — resume never re-creates
engini connect <app> --json                   # → {need:"objects", connection_id, objects, resume:"engini connect <app> --connection <id> --object <id>"}
engini connect <app> --connection <id> --object 5 --object 9

The same steps are available as standalone primitives: connections sign-in-url / oauth-complete (OAuth) and connections create / check / refresh / objects / select-objects.

Output & exit codes

Output adapts to context: human-readable on a TTY, compact JSON when piped, pretty JSON with --json. Every command also accepts:

• --json — pretty-print JSON
• --quiet — suppress non-essential output
• --schema — print the command's machine-readable arg schema (handy for agents)
• --dry-run — preview a mutating command without executing it

Exit codes are a stable contract: 0 success · 1 general error · 2 usage error · 3 authentication error · 4 not found · 5 validation error · 124 timeout.

Large results (token economy)

Tool outputs can be huge — an agent shouldn't pay tokens for data it hasn't asked for. When a tools call result exceeds --max-bytes (default 4096), it is spilled to a local sandbox and the command prints a compact envelope instead:

{ "handle": "h42", "history_id": 42, "data_size": 84211,
  "shape": { "type": "object", "keys": { "items": "array", "total": "number" } },
  "preview": { "id": 1, "email": "[email protected]" },
  "hint": "Full result stored. Pull data with: engini tools result h42 …" }

Then drill in with tools result <handle>, paying only for what you pull:

engini tools result h42 --select items.email      # 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   # page a list
engini tools result h42 --full                     # the whole payload
engini tools result --list                          # known handles
engini tools result --clear                         # wipe the sandbox

--inline (or --max-bytes 0) forces the full result inline; --raw / --llm emit the full output as before and bypass the sandbox. Stored results live under $XDG_CACHE_HOME/engini/results/ (%APPDATA% on Windows) and are auto-pruned to the most-recent 20, dropping anything older than 24h — so a handle is short-lived; drill in during the same session.

Configuration

Credentials and host config live in $XDG_CONFIG_HOME/engini/config.toml (%APPDATA%\engini\config.toml on Windows), written 0600. Resolution order is flags > environment > config; the env vars are ENGINI_API_KEY (preferred) or ENGINI_API_TOKEN, plus ENGINI_COMPANY_TOKEN.

Source & docs: https://github.com/engini/engini-sdk