CLI Reference

Install or update the APIMatic CLI with npm:

npm i -g @apimatic/cli@2

Commands overview

The APIMatic CLI groups its commands into these topics:

Quickstart: Set up your first developer portal, containing SDKs and Context Plugins.
Portal commands: Generate and serve developer portals.
API commands: Validate and transform API definitions.
SDK commands: Generate SDKs in C#, Python, and TypeScript, and publish them.
Plugin commands: Generate and publish Context Plugins for your published SDKs (Claude Code, Cursor, VS Code, Codex).
Publishing commands: List the publishing profiles you publish SDKs with.
Auth commands: Sign in, sign out, and check your sign-in status.
Autocomplete: Set up shell completion for apimatic commands.

Run apimatic --help to see all topics and commands.

Quickstart

apimatic quickstart

Interactive guide that sets up your first API portal. No prior setup needed. To generate an SDK on its own, use sdk generate.

Portal commands

`portal generate`

Generates a static API documentation portal from your src directory.

apimatic portal generate

Flag	What it does
`-i, --input`	Path to the parent directory that contains `src`, with your API definitions and configuration files. Defaults to `./`.
`-d, --destination`	Where to write the generated portal. Defaults to `<input>/portal`.
`-f, --force`	Overwrite changes without asking for your consent.
`--zip`	Write the generated portal as a `.zip` archive.
`-k, --auth-key`	Override the current authentication state with an API key.

`portal serve`

Builds the portal and serves it locally with hot reload.

apimatic portal serve --open

Flag	What it does
`-i, --input`	Path to the parent directory that contains `src`, with your API definitions and configuration files. Defaults to `./`.
`-p, --port`	Port for the local server. Defaults to `23513`.
`-o, --open`	Open the portal in your browser.
`-k, --auth-key`	Override the current authentication state with an API key.

API commands

`api validate`

Checks the syntax and semantics of an API definition.

apimatic api validate
apimatic api validate --file=<path>
apimatic api validate --url=<url>

With no flags, it validates the API definition in the src directory of the current folder. Use --input to point to another folder that contains src, or --file or --url to validate a single file.

Flag	What it does
`-i, --input`	Path to the parent directory that contains `src`, with your API definitions and configuration files. Defaults to `./`.
`--file`	Path to the API definition file to validate.
`--url`	URL of the API definition file to validate. The file must be publicly accessible.
`-k, --auth-key`	Override the current authentication state with an API key.

`api transform`

Converts an API definition between formats such as OpenAPI, RAML, WSDL, and Postman.

apimatic api transform --format=<format> --file=<path>

Flag	What it does
`--format`	Required. Format to convert to. See output formats for the values.
`--file`	Path to the API definition file to transform.
`--url`	URL of the API definition file to transform. The file must be publicly accessible.
`-d, --destination`	Directory where the transformed file is saved.
`-f, --force`	Overwrite changes without asking for your consent.
`-k, --auth-key`	Override the current authentication state with an API key.

SDK commands

`sdk generate`

Generates an SDK in the language you choose.

apimatic sdk generate --language=<language>

Supported values for --language: csharp, python, typescript.

To keep your changes to the generated SDK when you regenerate it, install Git 2.38 or later and make the SDK directory its own Git repository (--git-init does this for you). See Customize SDKs.

Flag	What it does
`-l, --language`	Required. SDK language: `csharp`, `python`, or `typescript`.
`-i, --input`	Path to the parent directory that contains `src`, with your API definitions and configuration files. Defaults to `./`.
`-d, --destination`	Where to write the SDK. Defaults to `<input>/sdk/<language>`.
`--stability`	`stable` or `beta`. Defaults to the level the language offers.
`--git-init`	Track the SDK directory with its own git repository so your customizations survive regeneration.
`-f, --force`	Never ask. Conflicts are resolved using the generator's changes, and an SDK that can't be merged is replaced, with a warning.
`-k, --auth-key`	Override the current authentication state with an API key.

`sdk publish`

Publishes an SDK to package registries (NuGet, PyPI, npm) and GitHub using a publishing profile. Run it with no flags, or with only --git-init, for guided mode, or pass flags for CI/CD. When you pass flags, --profile-id, --language, --version, and --publish-type are required.

Your changes to the SDK are merged before it is published, as sdk generate does with git 2.38 or later: with flags, always; in guided mode, add --git-init. Nothing is published while conflicts are left to resolve. See Customize SDKs.

apimatic sdk publish
apimatic sdk publish --profile-id=<id> --language=<lang> --version=<version> --publish-type=<type>

Flag	What it does
`-p, --profile-id`	ID of the publishing profile to use. Run `apimatic publishing profile list` to find it.
`-l, --language`	SDK language: `csharp`, `python`, or `typescript`.
`-v, --version`	Version to publish, in semantic versioning (`MAJOR.MINOR.PATCH`, for example `1.0.0`).
`--publish-type`	`package` (NuGet, PyPI, or npm) or `sourcecode` (GitHub). Pass it twice to publish both.
`-i, --input`	Path to the parent directory that contains `src`, with your API definitions and configuration files. Defaults to `./`.
`-d, --destination`	Where the generated SDK is saved locally. Defaults to `<input>/sdk/<language>`.
`--stability`	`stable` or `beta`. Defaults to the level the language offers.
`--dry-run`	Generate the SDK locally for review without publishing it.
`--git-init`	In guided mode, make the SDK directory a git repository when it isn't one of its own, so your changes to the SDK are kept. With flags, `sdk publish` always does this.
`-f, --force`	Never ask. Conflicts are resolved using the generator's changes, and an SDK that can't be merged is replaced, with a warning.

Plugin commands

`plugin generate`

Creates a Context Plugin for AI coding agents from your SDKs.

apimatic plugin generate

Flag	What it does
`-i, --input`	Path to the parent directory that contains `src`, with your API definitions and configuration files. Defaults to `./`.
`-d, --destination`	Where to write the plugin. Defaults to `<input>/plugin`.
`-f, --force`	Overwrite changes without asking for your consent.
`-k, --auth-key`	Override the current authentication state with an API key.

Note: Publish your SDKs with source code first (--publish-type=sourcecode) for the best results. Without published SDKs, the command builds a local plugin that you can preview.

`plugin publish`

Prints the git commands to publish your plugin to GitHub. It doesn't run them, so you can review what becomes public first.

apimatic plugin publish

Flag	What it does
`-i, --input`	Path to the parent directory that contains `src`, with your API definitions and configuration files. Defaults to `./`.
`-d, --destination`	Path where the plugin was generated. Defaults to `<input>/plugin`.

What the commands record

apimatic sdk publish and apimatic plugin generate keep their settings in src/apimatic.json, and create it if it doesn't exist.

After a successful publish, sdk publish updates the SDK's entry in languages, under publishing: the repository the source went to (--publish-type=sourcecode), the released version (--publish-type=package), and the package configuration from your publishing profile. --dry-run records nothing.
plugin generate covers the languages that languages names. The first time, it asks for the plugin's ID, name and version and records them in plugin, with your account name as author and MIT as license unless they're set. If languages names no language, it also asks which to cover and adds them. Later runs don't ask again. Where there's no terminal to ask in, such as CI, the first run stops: run it once in a terminal, or write the plugin block yourself.

Publishing commands

`publishing profile list`

Lists your publishing profiles with their IDs and enabled languages.

apimatic publishing profile list

Auth commands

Signs the APIMatic CLI in to your APIMatic account.

apimatic auth login

Flags: -k, --auth-key

`auth logout`

Clears your local credentials.

apimatic auth logout

`auth status`

Shows whether you're signed in and as whom.

apimatic auth status

Autocomplete

Prints the steps to turn on tab completion for apimatic commands in your shell.

apimatic autocomplete [SHELL]

SHELL is bash, zsh, or powershell. Leave it out to use your current shell.

Flag	What it does
`-r, --refresh-cache`	Rebuild the completion cache without printing the steps. Run it after upgrading the CLI so removed commands stop showing up.

Help

apimatic help <command>
apimatic <command> --help

Flags: -n, --nested-commands

Commands overviewCopy Anchor Link

QuickstartCopy Anchor Link

Portal commandsCopy Anchor Link

portal generateCopy Anchor Link

portal serveCopy Anchor Link

API commandsCopy Anchor Link

api validateCopy Anchor Link

api transformCopy Anchor Link

SDK commandsCopy Anchor Link

sdk generateCopy Anchor Link

sdk publishCopy Anchor Link

Plugin commandsCopy Anchor Link

plugin generateCopy Anchor Link

plugin publishCopy Anchor Link

What the commands recordCopy Anchor Link

Publishing commandsCopy Anchor Link

publishing profile listCopy Anchor Link

Auth commandsCopy Anchor Link

auth loginCopy Anchor Link

auth logoutCopy Anchor Link

auth statusCopy Anchor Link

AutocompleteCopy Anchor Link

HelpCopy Anchor Link

On this page