npm package: @membranehq/cli
Description: A command-line interface for working with Membrane in local development environment.
Latest version: 1.15.1

# Membrane CLI

A command-line interface for working with Membrane in local development environment.

## Installation

```bash
npm install -g @membranehq/cli
# or
yarn global add @membranehq/cli
# or
bun install -g @membranehq/cli
# or
pnpm install -g @membranehq/cli
```

## Quick Start

```bash
# Initialize with your workspace credentials (interactive)
membrane init

# Or non-interactive
membrane init --key <key> --secret <secret>

# Pull workspace elements
membrane pull

# Make changes, then push back
membrane push
```

See the Configuration section below for alternative ways to configure credentials.

## Authentication

Use `membrane login` to authenticate via browser-based OAuth. This stores your access token, refresh token, and the API URI locally.

```bash
# Login to the default Membrane API
membrane login

# Login to a self-hosted instance
membrane login --apiUri http://localhost:9000

# Non-interactive / headless: print the consent URL (stdin not a TTY behaves like this too)
membrane login --non-interactive

# Headless two-step flow (after `login start`, open URL, approve, then exchange the code)
membrane login --apiUri http://localhost:9000 start
membrane login complete <authorization-code>

# Check current login status, API URI, and project defaults
membrane status

# Log out and clear stored tokens
membrane logout
```

The `--apiUri` flag sets the API endpoint for this and all subsequent commands. Once logged in, the CLI remembers the API URI so you don't need to specify it again.

During login you select a default workspace and tenant. These defaults are saved in `.membrane/config.json` (project-level) **and** in the global `~/.membrane/credentials.json` (so commands run outside any project still have a fallback). Tenant API commands like `search`, `connection`, and `action` use these defaults unless you pass `--workspaceKey` / `--tenantKey`.

### How CLI commands authenticate

Commands fall into three groups based on which token type they need. The right client is chosen automatically — you only need to be logged in (`membrane login`) or have the relevant env vars set.

- **Account commands** (`status`, `logout`) — call account-level APIs with the platform-user OAuth JWT from `membrane login`.
- **Tenant API commands** (`connect`, `search`, `request`, `action`, `connection`, `connection-request`, `agent-session`) — call workspace/tenant APIs with a tenant-scoped JWT derived on demand from your platform-user token via `POST /org-workspaces/{id}/access-token`. Derived tokens are cached in `~/.membrane/credentials.json` and refreshed automatically when expired. Set `MEMBRANE_TOKEN` to bypass derivation entirely with a pre-minted bearer token.
- **Workspace management commands** (`pull`, `push`, `sync`, `diff`, `init`, `mcp`, `open`, `test`, `codegen`) — call workspace-management APIs with a workspace admin JWT minted locally from `workspaceKey + workspaceSecret` (read from `membrane.config.yml` or `MEMBRANE_WORKSPACE_KEY`/`MEMBRANE_WORKSPACE_SECRET` env vars). Set `MEMBRANE_TOKEN` to bypass minting and use a pre-supplied bearer token.

## Connecting External Apps

Use `membrane connect` to create a connection to a third-party service via browser-based OAuth. Requires prior authentication via `membrane login`.

```bash
# Connect using an integration key (uses defaults from login)
membrane connect --integrationKey hubspot

# Specify workspace and tenant explicitly
membrane connect --integrationKey hubspot --workspaceKey my-workspace --tenantKey my-customer

# Connect using a connector ID
membrane connect --connectorId 123

# Reconnect an existing connection
membrane connect --connectionId abc

# Print the connection URL instead of opening a browser
membrane connect --integrationKey hubspot --no-browser
```

## Tenant API commands

These commands call workspace APIs using the token from `membrane login`. They use your default workspace and tenant from login unless you pass `--workspaceKey` and `--tenantKey`. You can also pass a bearer token with `MEMBRANE_TOKEN` (see Configuration).

### Search workspace elements

```bash
membrane search "slack" --elementType connector
membrane search "invoice" --limit 20 --json
```

### Proxy HTTP requests to an external application through a connection

Make an HTTP request via the Membrane connection proxy (similar to curl):

```bash
membrane request <connectionId> /v1/resource
membrane request <connectionId> /items?page=1 -X GET
membrane request <connectionId> /items -X POST -d '{"name":"example"}' --json
```

Use `-H 'Header: value'` (repeatable), `--query key=value`, `--pathParam id=123`, and `--rawData` to send `--data` as a plain string.

### Manage connections

```bash
membrane connection list
membrane connection get <id>
membrane connection get <id> --wait              # Wait until not BUILDING
membrane connection ensure https://slack.com       # Find or create by app URL
membrane connection create "Connect to Slack"
```

### Manage actions (tools)

```bash
membrane action list
membrane action list --connectionId <id> --intent "send email"
membrane action get <id> --wait --json
membrane action create "Summarize the latest tickets"
membrane action run <actionId> --connectionId <id> --input '{"query":"..."}'
```

### Connection requests (OAuth flows)

Lower-level control of connection requests (browser `connect` is usually simpler):

```bash
membrane connection-request create --integrationKey hubspot
membrane connection-request get <requestId>
```

### Agent sessions

```bash
membrane agent-session list
membrane agent-session create --message "Add a HubSpot connector for contacts"
membrane agent-session get <sessionId> --wait
membrane agent-session send <sessionId> --message "Also add list sync"
membrane agent-session messages <sessionId>
membrane agent-session abort <sessionId>
```

Use `--agent <name>` with `create` to pick a specific agent when supported.

## Model Context Protocol (MCP)

Run an MCP server over stdio that exposes Membrane API operations as tools (for editors and agents that speak MCP):

```bash
membrane mcp
```

Requires `MEMBRANE_ACCESS_TOKEN`, or `MEMBRANE_WORKSPACE_KEY` and `MEMBRANE_WORKSPACE_SECRET` (or values in `membrane.config.yml` / after `membrane init`).

## Experimental commands

These may change or behave differently in future releases.

### Real-time sync (TUI)

```bash
membrane sync --watch              # Required: watch mode
membrane sync --watch --rps 5     # Optional: cap requests per second (1–1000)
```

### Interactive configuration

```bash
membrane config    # Interactive config UI (alias: membrane install)
```

### Code generation

From local workspace actions, generate OpenAPI or TypeScript. **Currently only schema generation is supported**, so `--schemasOnly` is required:

```bash
membrane codegen \
  --actions list-files,get-file-by-id \
  --out src/generated \
  --target openapi \
  --schemasOnly
```

`--target` is `openapi` or `typescript`.

### Integration tests

```bash
membrane test run connectors/hubspot
membrane test run actions/create-contact --fix
```

See `membrane test run --help` for path examples.

## Open workspace in console

`membrane open` uses workspace credentials (not OAuth login tokens). It requires `MEMBRANE_WORKSPACE_KEY` and `MEMBRANE_WORKSPACE_SECRET` in environment variables or `membrane.config.yml` (for example, after `membrane init`).

```bash
membrane open
```

## Synchronizing Workspace

Use `membrane init` to configure workspace credentials, then `membrane pull` and `membrane push` to synchronize workspace elements between local files and the remote workspace.

```bash
# Initialize workspace configuration
membrane init --key <key> --secret <secret>

# Pull workspace elements from remote
membrane pull [--force]

# Push workspace elements to remote
membrane push [--force]

# Show what would change on push without applying anything
membrane diff

```

## Configuration

The CLI can be configured using either environment variables or a configuration file (`membrane.config.yml`). Environment variables take precedence over the configuration file.

### Environment Variables

```bash
export MEMBRANE_WORKSPACE_KEY=<your-workspace-key>
export MEMBRANE_WORKSPACE_SECRET=<your-workspace-secret>
export MEMBRANE_API_URI=https://api.your-membrane-instance.com  # Optional: for self-hosted instances (default: https://api.integration.app)
export MEMBRANE_CONSOLE_URI=https://console.your-membrane-instance.com  # Optional: for self-hosted instances (default: https://console.integration.app)
export MEMBRANE_TEST_CUSTOMER_ID=<test-customer-id>  # Optional: for testing integrations
export MEMBRANE_ACCESS_TOKEN=<token>  # Optional: bearer token (e.g. for `membrane mcp`)
export MEMBRANE_TOKEN=<token>  # Optional: bypass workspace token exchange for tenant API commands
```

`MEMBRANE_ACCESS_TOKEN` and `MEMBRANE_TOKEN` are not interchangeable:

- `MEMBRANE_ACCESS_TOKEN` is used by `membrane mcp` to call the API directly (typically a workspace-scoped access token).
- `MEMBRANE_TOKEN` is a pre-minted bearer token. It's accepted by **both** tenant API commands (where it bypasses the platform-user→tenant derivation) **and** workspace management commands like `pull`/`push` (where it bypasses the local key+secret JWT mint). Pass whichever flavor of token you have — the API call will reject it if it lacks the required scope.

### Configuration File

The CLI uses a configuration file at `membrane.config.yml`:

```yaml
workspaceKey: <your-workspace-key>
workspaceSecret: <your-workspace-secret>

# Optional
apiUri: https://api.your-membrane-instance.com # For self-hosted instances (default: https://api.integration.app)
consoleUri: https://console.your-membrane-instance.com # For self-hosted instances (default: https://console.integration.app)

testCustomerId: test-customer # Internal ID of customer for testing integrations
```

**Note:** When both environment variables and configuration file are present, environment variables take precedence.

**Self-Hosting:** For details on self-hosting Membrane, see [Self-Hosting Documentation](https://getmembrane.com/features/self-hosting).

## Version Control

`membrane.config.yml` contains secrets. You should exclude it from version control.

`membrane` folder can and should be stored in version control to keep your integration configurations versioned.

## Transferring elements between workspaces with `pull` and `push`

The CLI provides a `pull` and `push` command to transfer workspace elements between environments. You'd typically use this to move integrations, actions, flows, and other configurations from development to production.

**How it works:**

Workspace elements (integrations, actions, data sources, flows, field mappings, etc.) are stored as YAML files in the `./membrane` directory. Each element has a unique UUID that identifies it across workspaces.

When you **pull**, the CLI:

- Exports all elements from the remote workspace as YAML
- Compares them with your local `./membrane` directory by UUID
- Identifies what's new, changed, or deleted in the remote workspace
- Downloads connector source code for custom connectors
- Updates your local files to match the remote state

When you **push**, the CLI:

- Packages your local `./membrane` directory as an export
- Compares it with the current state of the remote workspace
- Identifies what's new, changed, or deleted locally
- Uploads connector source code for custom connectors
- Applies the changes to the remote workspace

Changes are applied in dependency order (integrations before integration-level elements, parents before children) to maintain referential integrity. Conflicts occur when an element exists in only one location; use `--force` to resolve by preferring the source.

When you **diff**, the CLI:

- Compares current local state with the remote workspace
- Displays a unified diff of all changes

Useful for previewing what `push` would do before actually applying changes.

**Example:**

```bash
# Pull from development workspace
export MEMBRANE_WORKSPACE_KEY="dev-workspace-key"
export MEMBRANE_WORKSPACE_SECRET="dev-workspace-secret"
membrane pull

# Push to production workspace
export MEMBRANE_WORKSPACE_KEY="prod-workspace-key"
export MEMBRANE_WORKSPACE_SECRET="prod-workspace-secret"
membrane push
```

## License

MIT