Getting Started

Appmixer command-line tool.

The Appmixer CLI (appmixer on npm) is the command-line interface to the Appmixer engine. It talks to the same REST API the Designer and Backoffice use, so anything you can do in the UI you can also script from a terminal. It is used for three things:

• Building connectors. Scaffold a connector, run a component on your machine against the real third-party API, validate the source code, pack it, publish it to your instance and E2E-test it there. This is the reason most people install the CLI.
• Operating an instance. List, start, stop and inspect flows, manage service accounts, users, workspaces, data stores, system configuration, logs and telemetry, and transfer flows between instances.
• Driving Appmixer from scripts and AI agents. Every command that returns data supports --json, prints diagnostics to stderr and uses predictable exit codes, so the CLI works the same in a CI pipeline as it does for a coding agent.

This page is an introduction. The complete command reference with every option lives in the README on npm, and appmixer <command> --help is always authoritative for the version you have installed. This page describes Appmixer CLI 2.6.0.

AI-Assisted Connector Development

The fastest way to build a connector today is to let a coding agent do it. The public appmixer-skills repository contains agent skills that drive the CLI end to end:

Skill	What it does
build-connector	Scaffolds a connector from requirements: authentication module, components, manifests, icons.
test-connector	Runs the components with real API calls and executes E2E test flows on your instance.
review-connector	Audits a connector against the Appmixer connector standards without modifying anything.

The skills use the CLI as their only external tool, which is why every command has a --json mode. They install as a Claude Code plugin:

claude
/plugin marketplace add Appmixer-ai/appmixer-skills
/plugin install appmixer@appmixer-skills

Other agents (Cursor, Copilot, Windsurf, Cline) install them with npx skills add Appmixer-ai/appmixer-skills. The skills need the CLI installed, pointed at an instance and logged in, which is exactly what the rest of this page sets up.

The older appmixer ai commands are deprecated in favour of appmixer-skills.

Installation

Node.js 18.15 or newer is required (https://nodejs.org).

npm install -g appmixer
appmixer --version

Connecting to an Appmixer Instance

Point the CLI at the API host of your instance (not the Designer UI) and log in. For a local or trial installation the API is usually http://localhost:2200.

appmixer url https://api.appmixer.com
appmixer login [e-mail]     # prompts for the password, stores a JWT
appmixer login --sso              # accounts without a password (SAML/OIDC): signs in through the browser

Sessions are kept per instance. Store each URL under an alias and appmixer alias switches both the URL and the session:

appmixer url https://api.appmixer.com prod
appmixer url http://localhost:2200 local
appmixer login [e-mail] prod
appmixer login [e-mail] local
appmixer alias local              # switch instance: URL and session
appmixer alias                    # list aliases; * marks the ones you are logged into
appmixer logout --all             # forget every stored session

The configuration lives in ~/.config/configstore/appmixer.json. Tokens are stored in plain text, so treat the file the way you treat ~/.aws/credentials.

In CI and other non-interactive environments, set APPMIXER_API_URL and APPMIXER_TOKEN (a pre-obtained JWT) instead of logging in. APPMIXER_WORKSPACE runs every command inside a workspace. The remaining environment variables and the SSO options are described in the npm README.

Your First Connector

The example generator produces a complete connector: a service, a module and one component. The no-auth type asks the user for no credentials, so there is nothing to configure.

$ appmixer init example no-auth
Created directory structure ./appmixer/myservice/mymodule/MyComponent
Creating component appmixer.myservice.mymodule.MyComponent
Created component manifest file ./appmixer/myservice/mymodule/MyComponent/component.json.
Created component package file ./appmixer/myservice/mymodule/MyComponent/package.json.
Created component behaviour file ./appmixer/myservice/mymodule/MyComponent/MyComponent.js.
Created service manifest file ./appmixer/myservice/service.json.
Created quota module file ./appmixer/myservice/quota.js.

Example successfully generated.

The directory layout and the meaning of every manifest file are described in Basic Structure.

Test the component locally

appmixer test component runs the component on your machine and shows what it emits. Send a message to its input port:

appmixer test component appmixer/myservice/mymodule/MyComponent -i '{ "in": { "sourceData": "foo" } }'

The output contains the incoming message, everything the component sent to its output ports, the return value of receive, its final state and any errors it threw, for example [ERROR]: myBadError is not defined for a typo in the behaviour file.

On Windows, escape the JSON arguments: appmixer test component MyComponent -i "{\"in\": {\"sourceData\": \"foo\"}}".

Publish your component

Before you publish, your user account must have the vendor property set to a string or an array of strings, matching the vendor used in the components you are publishing. If your company is called acme, set vendor to acme. More about vendors in Basic Structure. You can set the property in Backoffice:

Using Backoffice to set vendor property.

appmixer pack zips the connector (node_modules, .git and hidden files are excluded) and appmixer publish uploads the archive:

appmixer pack ./appmixer/myservice -o myservice.zip
appmixer publish myservice.zip

The component is now published and ready to be used:

Custom component published

The labels and icons of the service in the component panel and of the component in the Inspector match the service.json and component.json manifests.

Publishing again replaces the previous version, which is how you update a connector. appmixer remove <type> deletes a component, module or service from the instance; this cannot be undone and running flows that use it start failing.

Command Overview

appmixer --help lists every command and appmixer <command> --help every subcommand. Grouped by what they are for:

Area	Commands	Notes
Connection	url, alias, login, logout	See above.
Connector development	init, test, connector, pack, publish, update, download, remove, component, app, bundle	init openapi generates a connector from an OpenAPI spec, see OpenAPI Connector Generator; init mcp wraps an MCP server. connector validate checks the source offline, connector verify runs it against the live API. component call executes a component function without building a flow.
E2E testing	e2e	Imports test flows into the instance, runs them and reports results. Used by test-connector.
Flows	flow	List, get, create, clone, start, stop, versions, drafts, variables, triggers, test mode, metrics.
Accounts and auth	account, auth	Service accounts and component-to-account bindings, OAuth helpers.
Users and access	user, workspace, acl, resources	Users, workspaces (user groups), ACL rules.
Configuration	config, service-config, user-service-config	Instance-level, per-service and per-user configuration.
Data	store, file, public-file	Data stores and file storage.
Observability	logs, telemetry, stats, chart, dead-letter	Search or tail logs, telemetry, usage statistics, unprocessed messages.
Administration	system, quota, category, price-list, listener	Instance administration.
Integrations	integration, url-alias, automation-hub	Integration templates and instances, stable webhook URLs, Automation Hub settings.
Other	modifiers, transfer	Variable modifiers; moving flows and their dependencies between instances.

Conventions every command follows:

• --json prints machine-readable output to stdout; progress and errors go to stderr.
• Exit code 0 means success, 1 failure. The e2e commands add task-specific codes documented in their --help.
• Commands taking a payload accept --data '<json>', --file <path> or piped stdin.
• --workspace <name|id> runs a single command inside a workspace.

Where to Go Next

• Appmixer CLI on npm: the complete command reference for every command listed above.
• appmixer-skills: build, test and review connectors with a coding agent.
• Building Connectors: manifests, behaviour, authentication modules and everything else a connector is made of.
• MCP Servers: wrap an MCP server package as a connector.