Skip to main content

APIMatic CLI Commands

The APIMatic CLI empowers engineering teams and API providers to automate key aspects of the API lifecycle, such as validation, transformation, SDK generation, and documentation portal delivery, directly from the command line.

note

For installation and getting started, see Installing APIMatic CLI and Getting Started Guide.

Command Topics Overview​

The APIMatic CLI groups commands into the following topics:

  • Quickstart: Get started with your first API documentation portal or SDK.
  • Portal Commands: Generate, serve, and manage API documentation portals.
  • API Commands: Validate and transform API specifications.
  • SDK Commands: Generate and publish SDKs for your APIs in multiple languages.
  • Plugin Commands: Generate a context plugin for your published SDKs (Claude Code, VS Code, Cursor).
  • Publishing Commands: Manage SDK publishing configurations.
  • Auth Commands: Manage authentication for CLI operations.

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

Note:
All command flags are optional unless marked as (required).

Quickstart​

This interactive command will guide you step-by-step through setting up and visualizing your first API portal or generating your first SDK, no prior setup required!

Start here:

apimatic quickstart

No flags required.

This command is the best way to get hands-on with APIMatic Docs as Code and see results instantly. This will setup a build directory for you directly. The name of the build directory is set as src. To learn more about the build directory, visit the Contents of the Build Directory.

Portal Commands​

Easily generate and manage your API portal right from the terminal, seamlessly integrating documentation, SDKs, and code samples into your CI/CD pipelines and developer workflows.

Generate a Portal​

Once you're comfortable with the build directory structure, you can generate a static API documentation portal from your src directory. This is perfect for integrating into your automation scripts or release process.

apimatic portal generate

The generated portal will be downloaded to the location specified by the --destination flag. To preview the portal, use the serve command below in the Preview Locally section.

Flags:

  • --input=<value> : Path to the parent directory containing the 'src' directory, which includes API specifications and configuration files. Defaults to ./.
  • --destination=<value> : Path where the portal will be generated. Defaults to <input>/portal.
  • --force, -f : Overwrite if a portal exists in the destination.
  • --zip : Download the generated portal as a .zip archive.
  • --auth-key=<value> : Override current authentication state with an authentication key.

Preview Locally​

During development, you can build and serve your API documentation portal locally with hot reload. The portal serve command combines portal generation and serves your portal too. This makes it easy to preview changes and iterate quickly.

apimatic portal serve --open

Flags:

  • --input=<value> : Path to the parent directory containing the 'src' directory, which includes API specifications and configuration files. Defaults to ./.
  • --destination=<value> : Path where the portal will be generated. Defaults to <input>/portal.
  • --port, -p <value> : Port to serve the portal. Defaults to 3000.
  • --open, -o : Open the portal in the default browser.
  • --ignore, -i <value> : Comma-separated list of files/directories to ignore.
  • --auth-key=<value> : Override current authentication state with an authentication key.
  • --no-reload : Disable hot reload.

Generate a Table of Contents (TOC)​

Automatically create a TOC YAML file for your portal content and specs. This helps organize your documentation for a better developer experience, and controls the way sections are displayed in your portal's side navigation bar.

apimatic portal toc new

Flags:

  • --destination=<value> : Optional path where the generated TOC file will be saved. Defaults to <input>/src/content.
  • --input=<value> : Path to the parent directory containing the 'src' directory, which includes API specifications and configuration files. Defaults to ./.
  • --force : Overwrite the TOC file if one already exists at the destination.
  • --expand-endpoints : Include individual entries for each endpoint in the generated TOC. Requires a valid API specification in the working directory.
  • --expand-models : Include individual entries for each model in the generated TOC. Requires a valid API specification in the working directory.
  • --expand-webhooks : Include individual entries for each webhook in the generated TOC. Requires a valid API specification in the working directory.
  • --expand-callbacks : Include individual entries for each callback in the generated TOC. Requires a valid API specification in the working directory.

Learn more about the TOC file here.

Create API Recipes​

Generate an API Recipe file to provide step-by-step guides or workflows within your documentation portal.

apimatic portal recipe new

Flags:

  • --name=<value> : Name for the recipe.
  • --input=<value> : Path to the parent directory containing the 'src' directory, which includes API specifications and configuration files. Defaults to ./.

You can read more about API Recipes here.

Configure API Copilot​

Add the API Copilot configuration to your APIMATIC-BUILD.json file. This feature allows you to integrate AI-powered assistance into your API documentation portal.

apimatic portal copilot

Flags:

  • --input=<value> : Path to the parent directory containing the 'src' directory, which includes API specifications and configuration files. Defaults to ./.
  • --disable : Marks the API Copilot as disabled in the configuration.
  • --auth-key=<value> : Override current authentication state with an authentication key.

API Commands​

The APIMatic CLI makes it easy to ensure your API specifications generate optimal quality SDKs and documentation. Whether you're validating a new OpenAPI file, converting between formats, or preparing for SDK generation, these commands help you automate and standardize your API quality checks.

Validate Your API​

Before you generate SDKs or publish documentation, it's a best practice to validate your API specification. The APIMatic CLI can check both the syntax and semantics of your API files so you can catch issues early and resolve them on-the-go.

apimatic api validate --file=./specs/sample.json
apimatic api validate --url=https://petstore.swagger.io/v2/swagger.json

Flags:

  • --file=<value> : Path to the API specification file to validate.
  • --url=<value> : URL to the specification file to validate. Can be used in place of the --file option if the API specification is publicly available.
  • --auth-key=<value> : Override current authentication state with an authentication key.

Transform API Specifications​

Need to convert your API definition from one format to another? The transform command supports a wide range of formats (OpenAPI, RAML, WSDL, Postman, and more), making it easy to integrate with different tools or partners. This is especially useful for teams working across multiple API ecosystems.

apimatic api transform --format=OpenApi3Json --file=./specs/sample.json
apimatic api transform --format=RAML --url="https://petstore.swagger.io/v2/swagger.json"

Flags:

  • --format=<value> : (required) Specification format to transform API specification into. Run the command with the --help flag to see all options available.
  • --file=<value> : Path to the API specification file to transform.
  • --url=<value> : URL to the API specification file to transform. Can be used in place of the --file option if the API specification is publicly available.
  • --destination=<value> : Directory to download transformed file to. Defaults to ./.
  • --force, -f : Overwrite if same file exists in the destination.
  • --auth-key=<value> : Override current authentication state with an authentication key.

SDK Commands​

Accelerate developer adoption and integration by generating SDKs for your APIs in popular programming languages.

Generate SDKs​

With a single command, you can generate SDKs for your API in languages like Python, Java, C#, TypeScript, Ruby, PHP, and more. Input can be a local API Specification file or a remote URL, making it easy to fit into any workflow.

apimatic sdk generate --language=python

Flags:

  • -l, --language=<value> : (required) programming language for SDK generation. Run the command with the --help flag to see all options available.
  • -i, --input=<value> : Path to the parent directory containing the 'src' directory, which includes API specifications and configuration files. Defaults to ./.
  • -d, --destination=<value> : Directory where the SDK will be generated. Defaults to <input>/sdk/<language> or <input>/sdk/<api-version>/<language>.
  • --api-version=<value> : Version of the API to use for SDK generation (if multiple versions exist)
  • --skip-changes : Don't apply the saved changes to the generated SDK
  • --track-changes : Generate SDK source tree in the src directory to enable tracking changes across generations
  • --codegen-version=<option> : Version of the code generator to use. Defaults to v3. Options: v3, v4.
  • --stability=<option> : Stability level of the generated SDK. Defaults to stable. Options: stable, beta.
  • -f, --force : Overwrite if an SDK already exists in the destination.
  • -k, --auth-key=<value> : Override current authentication state with an authentication key.
  • --zip : Download the generated SDK as a .zip archive

Save SDK Changes​

If you've customized a generated SDK, this command saves those changes so they can be tracked and reused across future SDK generations.

apimatic sdk save-changes --language=java --sdk=./sdk

Flags:

  • -i, --input=<value> : Path to the parent directory containing the 'src' directory, which includes API specifications and configuration files. Defaults to ./.
  • -l, --language=<value> : (required) programming language for SDK generation. Run the command with the --help flag to see all options available.
  • --sdk=<value> : Path to the folder containing the updated SDK. Defaults to ./sdk/<language> or ./sdk/<api-version>/<language>.
  • --api-version=<value> : Version of the API to use for saving changes (if multiple versions exist).

Publish an SDK​

Generate and publish an SDK to a package registry (for example npm, PyPI, NuGet) and/or a source code repository (on GitHub) using a publishing profile configured in the APIMatic App.

Run without flags for a step-by-step interactive experience:

apimatic sdk publish

For non-interactive mode, pass all the required flags that's --profile-id, --language, --version, and --publish-type:

apimatic sdk publish --profile-id=a1b2c3d4e5f6a1b2c3d4e5f6 --language=typescript --version=1.0.0 --publish-type=package

Flags:

  • -p, --profile-id=<value> : ID of the publishing profile to use. Run apimatic publishing profile list to find your profile ID.
  • -l, --language=<value> : Language of the SDK to generate and publish. Run the command with --help to see all supported options.
  • -v, --version=<value> : Semantic version of the SDK to publish (like 1.0.0).
  • --publish-type=<value> : One or more publishing targets: package for a package registry, sourcecode for a git repository.
  • --input=<value> : Path to the parent directory containing the src directory with your API specification files. Defaults to ./.
  • --destination=<value> : Directory where the generated SDK will be saved locally. Defaults to <input>/sdk.
  • --dry-run : Generate the SDK locally for review without publishing.
  • -f, --force : Overwrite existing SDK output without prompting.
  • --update-plugin-config : Record the published SDK in plugin-config.json, creating the file if it doesn't exist. Interactive runs are asked instead. Ignored with --dry-run.

Plugin Commands​

Build a context plugin from your published SDKs, so an AI coding agent such as Claude Code, VS Code, or Cursor writes integration code against the SDK you actually shipped rather than from model memory.

Generate a Context Plugin​

note

This command generates context plugins for codegen v4 SDKs only. SDKs generated with codegen v3 are covered by the context plugin bundled with your generated API portal instead.

Generate a context plugin covering the SDKs recorded in plugin-config.json, creating that file for you if it doesn't exist yet. Publish an SDK first: publishing is what records the languages the plugin covers.

apimatic plugin generate

The command asks for an ID for the plugin (lower-case words separated by single dashes, such as acme-payments), a display name, and a version, then writes the plugin to ./plugin.

Each SDK must be published to GitHub for the plugin to cover it. When you publish, include source code publishing (--publish-type=sourcecode), which pushes the generated SDK to the GitHub repository configured in your publishing profile. The plugin points AI agents at that repository for the SDK source code, so a language recorded from a package-only publish carries no repository for the plugin to use, and the CLI warns you when it finds one. See the SDK Publishing Overview for how publishing profiles and publishing targets work.

Flags:

  • -i, --input=<value> : Path to the parent directory containing the src directory, which includes your API specifications and plugin-config.json. Defaults to ./.
  • -d, --destination=<value> : Path where the plugin will be generated. Defaults to <input>/plugin.
  • -f, --force : Overwrite an existing plugin directory without prompting.
  • -k, --auth-key=<value> : Override current authentication state with an authentication key.

Publish a Context Plugin​

Print the git commands that publish a generated context plugin to a GitHub repository.

apimatic plugin publish

This command prints the commands and stops there. It never touches your repository: nothing is created, committed, or pushed on your behalf. Before printing them, it reports how many files and directories are about to become public, because the repository it proposes is a public one.

On a first publish it prints the full sequence, using your plugin ID as the repository name and your plugin version as the tag:

cd "./plugin"
git init -b main
gh repo create acme-payments --public --source=. --remote=origin
git add . && git commit -m "Publish acme-payments 0.1.0"
git push -u origin main
git tag v0.1.0 && git push origin v0.1.0

Once the plugin directory is already a git repository, it prints the shorter sequence for a new release instead, skipping the setup steps and going straight to committing, pushing, and tagging.

Flags:

  • -i, --input=<value> : Path to the parent directory containing the src directory. Defaults to ./.
  • -d, --destination=<value> : Path to the generated plugin. Defaults to <input>/plugin.

The plugin-config.json File​

Both apimatic sdk publish and apimatic plugin generate read and write a plugin-config.json in your src directory, and each owns a different half of it. apimatic sdk publish records the languages, including the source repository, package configuration, and code generator version for each SDK it publishes. apimatic plugin generate fills in the plugin's own identity. Unrecognized fields won't be removed, so a hand-edited file keeps whatever you added to it.

When you run apimatic sdk publish without any flags, it runs an interactive wizard. Interactive publishes ask before recording a language. For CI/CD, where a prompt is never answered, pass --update-plugin-config to apimatic sdk publish instead. The flag is ignored with --dry-run, which publishes nothing and so has no published SDK to record.

Publishing Commands​

Manage the publishing profiles used to distribute your SDKs to package registries and source repositories.

List Publishing Profiles​

Display all publishing profiles associated with your account, including each profile's name, ID, and enabled languages. Use this command to find the profile ID required for sdk publish.

apimatic publishing profile list

No flags required.

Auth Commands​

Manage authentication for secure CLI operations. You can login using your APIMatic credentials or your APIMatic-provided API key from your account settings page.

Log In​

Authenticate your CLI session using your APIMatic credentials or your APIMatic-provided API Key. This is required for most operations that interact with APIMatic's platform.

apimatic auth login

Flags:

  • --auth-key=<value> : Can be provided to manually set authentication key for all commands.

Log Out​

Quickly clear your local authentication credentials if you're switching users or need to reset your session.

apimatic auth logout

No flags required.

Check Authentication Status​

Not sure if you're logged in or which account is active? Use this command to view your current authentication state.

apimatic auth status

No flags required.

In-Depth Help​

Need more details about a command or topic? The help command gives you usage, options, and examples for any CLI command.

apimatic help portal generate --nested-commands

Flags:

  • --nested-commands, -n : Include all nested commands in the output.

For a full list of options and advanced usage, run any command with the --help flag.