# Connxio CLI

Connxio CLI provides the `connxio` command and an MCP server for Connxio management APIs.

The current implementation focuses on MCP usage through:

```bash
connxio mcp serve
```

## Prerequisites

- Node.js 24 or newer
- Connxio OAuth client credentials
- A Connxio subscription-scoped API key for each subscription context you want to use

## Install

Install the CLI globally from npm:

```bash
npm i -g @connxio/cli
```

Verify installation:

```bash
connxio --help
```

## Configure OAuth

```bash
connxio auth configure
```

You will be prompted for:

- OAuth client id
- OAuth scope, defaulting to `api://connxio/.default`
- OAuth client secret

Check status:

```bash
connxio auth status
```

Clear OAuth configuration:

```bash
connxio auth clear
```

You can also configure OAuth with environment variables:

```bash
CONNXIO_OAUTH_CLIENT_ID="<client-id>"
CONNXIO_OAUTH_CLIENT_SECRET="<client-secret>"
CONNXIO_OAUTH_TOKEN_URL="https://api.connxio.com/oauth/token"
CONNXIO_OAUTH_SCOPE="api://connxio/.default"
```

`CONNXIO_OAUTH_TOKEN_URL` and `CONNXIO_OAUTH_SCOPE` are optional overrides.

## Configure Contexts

A context represents one Connxio subscription. Connxio API keys are subscription-scoped, so add one context for each subscription you want to use.

```bash
connxio context add
```

The CLI calls `/v2/subscriptions/current` with the provided API key and stores the subscription/company metadata locally. API keys are stored through the credential abstraction, not in `config.json`.

List contexts:

```bash
connxio context list
```

Set a default context:

```bash
connxio context default <context-id>
```

Remove a context:

```bash
connxio context remove <context-id>
```

## Register With VS Code

VS Code 1.99+ supports MCP servers natively via GitHub Copilot agent mode.

**Option 1 — user settings (all projects)**

Open the command palette (`Ctrl+Shift+P`/`Cmd+Shift+P`) and select `MCP: Add server`.

Select `stdio` transport, `connxio mcp serve` as the command, and set the name to `connxio`. This will create a user-level MCP server registration that is available in all projects.

Alternatively, edit the user level mcp.json config file directly. Open the command palette and select `MCP: Open User Configuration`, then add:

```json
{
  "servers": {
    "connxio": {
      "type": "stdio",
      "command": "connxio",
      "args": ["mcp", "serve"]
    }
  }
}
```

**Option 2 — workspace settings (this project only)**

Create `.vscode/mcp.json` in your project root:

```json
{
  "servers": {
    "connxio": {
      "type": "stdio",
      "command": "connxio",
      "args": ["mcp", "serve"]
    }
  }
}
```

The Connxio MCP server will now be available when you open this project in VS Code.

If you need to pass environment variables (e.g. for OAuth or a custom API base URL), add an `env` block:

```json
{
  "servers": {
    "connxio": {
      "type": "stdio",
      "command": "connxio",
      "args": ["mcp", "serve"],
      "env": {
        "CONNXIO_OAUTH_CLIENT_ID": "<client-id>",
        "CONNXIO_OAUTH_CLIENT_SECRET": "<client-secret>"
      }
    }
  }
}
```

Do not commit files containing OAuth client secrets to source control.

## Register With Claude Code

Register the installed MCP server:

```bash
claude mcp add --transport stdio connxio -- connxio mcp serve
```

To register the MCP server at user level (available in all projects), add `--scope user`:

```bash
claude mcp add --scope user --transport stdio connxio -- connxio mcp serve
```

Verify registration:

```bash
claude mcp list
```

If you need to replace an existing registration:

```bash
claude mcp remove connxio
claude mcp add --transport stdio connxio -- connxio mcp serve
```

## API Base URL

The default API base URL is:

```text
https://api.connxio.com
```

Override it per context:

```bash
connxio context add --base-url http://localhost:5119/api
```

Or with an environment variable:

```bash
CONNXIO_API_BASE_URL="http://localhost:5119/api"
```

For localhost development with self-signed HTTPS certificates, the CLI automatically allows insecure TLS for localhost URLs. For other local development endpoints, use:

```bash
CONNXIO_INSECURE_TLS=true
```

Do not use insecure TLS settings in production.

## Run Diagnostics

```bash
connxio mcp doctor
```

For HTTP troubleshooting, enable redacted request diagnostics:

```bash
CONNXIO_DEBUG_HTTP=true connxio mcp doctor
```

## MCP Tools

The MCP server exposes Connxio v2 management operations and v3 action-based integrations, schemas, performance metrics, persisted errors, and testing.

Context and subscription tools:

- `list_contexts`
- `get_current_context`
- `list_subscriptions`
- `get_current_subscription`

Integration tools:

- `list_integrations`
- `get_integration`
- `create_integration`
- `create_integration_no_validation`
- `update_integration`
- `delete_integration`

All integration tools accept `apiVersion: "v2" | "v3"` (default: `"v2"`). Choose `"v3"` for action-based integrations. The API derives action-based mode from `triggers` or `actions`; `isActionBased` is computed, not a writable flag. Integration write bodies accept optional `archived` (boolean, API default false), which is forwarded along with the other configuration properties. The v3 create tools upsert; the no-validation variant skips graph validation and disables invalid configurations.

Code component tools:

- `list_code_components`
- `get_code_component`
- `get_code_component_versions`
- `create_code_component`
- `deprecate_code_component`
- `rename_code_component`
- `delete_code_component`

Environment variable tools:

- `list_environment_variables`
- `get_environment_variable`
- `create_environment_variable`
- `delete_environment_variable`

Security configuration tools:

- `list_security_configs`
- `get_security_config`
- `create_security_config`
- `delete_security_config`

Schema tools (v3, scoped to the current company):

- `list_schemas` — latest metadata, without content
- `get_schema` — latest version with content
- `get_schema_versions` — all versions with content, newest first
- `get_schema_content` — content for `id` and `schemaVersion`
- `upload_schema` — create a schema or add a new version
- `deprecate_schema` — toggle a version's deprecated state; calling again restores it
- `delete_schema` — permanently delete all versions; fails if an integration references the schema

`upload_schema` accepts a `schema` object with `id`, `name`, `version`, `type`, and base64-encoded `content`. Optional metadata: `description`, `webhookConnectionId`, `originalFilename`, and `uploadedBy`. Versions cannot be overwritten; an existing schema's name and type must match.

Performance and persisted error tools (v3):

- `list_company_performance_metrics`
- `list_subscription_performance_metrics`
- `list_integration_performance_metrics`
- `get_interchange_performance_metric`
- `list_subscription_errors`
- `list_integration_errors`
- `get_interchange_error`

List tools accept optional `from` and `to` ISO 8601 timestamps with UTC offsets, `skip` (0–100,000; default 0), and `size` (1–1,000; default 100). They return one API page including counts and `hasNextPage`; request the next page by increasing `skip` by `size`. Performance dates default to the last 24 hours; omitted error dates include all retained errors. Integration lists require `integrationId`. Interchange lookups require `interchangeId` and do not take date or paging filters.

Performance company and integration queries cover subscriptions within the current company. Persisted error queries are limited to the current subscription. An empty integration error page can also mean the integration does not exist.

Testing tools (v3, scoped to the current subscription):

- `list_test_groups`
- `get_test_group`
- `create_test_group`
- `update_test_group`
- `delete_test_group`
- `upload_test_file`
- `get_test_file` — uploaded file metadata
- `download_test_file` — original bytes saved to a new local file
- `start_test_run`
- `list_test_runs`
- `get_test_run`

Create/update tools accept a `group` object containing `name`, a nonempty list of unique `integrationIds`, and optional `assertions` mapping integration IDs to node IDs to CxMaL expressions. Updating replaces these fields: omitted or empty assertions clears existing assertions. On a `409`, reload the group before editing again. Deleting a group cleans retained run history and requires `confirm: true`.

Upload one nonempty fixture per integration using `groupId`, `integrationId`, and either `source: { "type": "text", "content": "..." }` or `source: { "type": "file", "filePath": "/path/to/fixture" }`. Text is sent as UTF-8; local file bytes are sent verbatim. Optional `fileName`, `contentType`, and `isBinary` override inferred metadata. Local files infer JSON, XML, plain text, or binary content types from their extension; binary defaults to true for `application/octet-stream`. Inline text defaults to plain text and the API's `{integrationId}.txt` filename. For example, use `contentType: "application/json"` and `fileName: "input.json"` for inline JSON. JSON/XML content is never wrapped in a JSON string.

`download_test_file` requires a local destination `filePath`; its parent directory must exist. It returns an absolute path and byte count, preserves original bytes, and refuses to overwrite an existing file. Local paths refer to the machine running the MCP server.

`start_test_run` starts real integration execution and requires all group fixtures before submission. It returns run metadata immediately and never automatically retries a failed submission. Optional `connxioApiKeyId` is an API key **ID**, never a secret. Check history before manually resubmitting after an uncertain response.

`list_test_runs` returns one API page with counts and `hasNextPage`. Optional `skip` ranges from 0–100,000 (default 0); `size` ranges from 1–1,000 (default 100). Increase `skip` by `size` to continue. History contains run metadata; use `get_test_run` for evaluated results.

`get_test_run` takes `groupId`, `runId`, optional `waitSeconds` (0–60, MCP default 0), and optional `includeStatusEvents` (API default false). It performs one lookup or bounded wait, without automatic polling. Inspect `run.status` and `run.isComplete`: HTTP 202 means running; HTTP 200 includes completed failures. Status values are `InProgress`, `Passed`, `Failed`, `Terminated`, and `Timeout`. Assertion verdicts are returned even without detailed events; disconnecting a wait does not cancel execution.

Standalone integration testing tools (v3, scoped to the current company and subscription):

- `upload_integration_test_file`
- `get_integration_test_file` — standalone fixture metadata
- `download_integration_test_file`
- `start_integration_test_run`
- `list_integration_test_runs`
- `get_integration_test_run`

These tools use `integrationId` without a `groupId` and support both legacy and action-based integrations through `/v3/integrations/{integrationId}/testfile` and `/testruns`. Standalone fixtures and history are separate from group fixtures and history; they share the portal's standalone test storage. In standalone run metadata, `testGroupId` equals `integrationId`. Configuration snapshots stay internal to the API.

File upload/download inputs and byte-preservation behavior match the group tools. Uploads require `contextId`; text/file `source`, `contentType`, `fileName`, and `isBinary` work identically. The API normalizes stored filenames to printable ASCII basenames. Downloads require a new destination `filePath` and never overwrite an existing file.

`start_integration_test_run` requires `contextId` and a nonempty saved standalone fixture. Missing/empty fixtures fail before execution. Optional `triggerId` selects an existing trigger and is not necessarily a GUID. **Omitting `triggerId` skips inbound processing**, matching the portal; supply it to run the selected trigger. Optional `connxioApiKeyId` is a key ID, never a secret. Submission returns run metadata and `resultsUrl` without waiting for completion or automatically retrying.

`list_integration_test_runs` uses the same `skip`/`size` bounds and returns one page with paging metadata, including portal-created standalone runs. `get_integration_test_run` requires `integrationId` and `runId`, defaults to `waitSeconds: 0`, supports waits up to 60 seconds, and accepts `includeStatusEvents`. Inspect `run.status` and `run.isComplete`; a completed failure remains a successful HTTP 200 response, while an unfinished run returns 202. Disconnecting a wait does not cancel execution.

Write tools require `contextId`. Destructive tools require `contextId` and `confirm: true`.

`/messages` operations are intentionally not exposed yet.

## Local Config Files

Non-secret config is stored in:

- macOS/Linux: `${XDG_CONFIG_HOME:-~/.config}/connxio/config.json`
- Windows: `%APPDATA%\connxio\config.json`

Secrets are stored through the CLI credential abstraction. The CLI now uses the OS keyring when available and falls back to `${XDG_CONFIG_HOME:-~/.config}/connxio/credentials.json` on macOS/Linux or `%APPDATA%\connxio\credentials.json` on Windows when secure storage is unavailable.

If you already have secrets in `credentials.json`, the CLI migrates them into the OS keyring lazily as they are used and removes the legacy file entries after a successful migration.