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:

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

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

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.

tip

If you haven't used the APIMatic CLI before, start with the Quickstart Command to set up your first portal in minutes.

How Portal Generation Works​

To generate an API Portal, your project directory should be organized as follows:

  • A content directory for Markdown guides and documentation.
  • A spec directory for your API specification files.
  • A static directory for images or other static assets referenced in your docs.
  • A configuration file named APIMATIC-BUILD.json to tie everything together.

If you're new to this structure, don't worry! You can explore a ready-made example in this GitHub repository. For a deeper dive into the required input format, check out How to prepare the Build Input.

Quickstart​

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

Start here:

apimatic portal:quickstart

No flags required.

This command is the best way to get hands-on with APIMatic Docs as Code and see results instantly.

Generate a Portal​

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

apimatic portal:generate --folder="./input-folder" --destination="./generated_portal" --force --zip --auth-key=YOUR_API_KEY

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:

  • --folder=<value> : Path to the input directory containing API specifications and Build Config file. Defaults to ./.
  • --destination=<value> : Path to the downloaded portal. Defaults to ./generated_portal.
  • --force, -f : Overwrite if a portal exists in the destination.
  • --zip : Download the generated portal as a .zip archive.
  • --auth-key=<value> : Can be provided to 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 --source=./ --destination=./generated_portal --port=3000 --open --ignore=temp,temp-file.json --auth-key=YOUR_API_KEY --no-reload

Flags:

  • --source, -s <value> : Source directory containing specs, content, and Build Config file. Defaults to ./.
  • --destination, -d <value> : Directory to store and serve the generated portal. Defaults to ./generated_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> : Can be provided to 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 --destination=./portal/content/ --folder=./my-project --force --expand-endpoints --expand-models

Flags:

  • --destination=<value> : Optional path where the generated TOC file will be saved. Defaults to the current working directory.
  • --folder=<value> : Path to the working directory containing the API project files. Defaults to the current working directory.
  • --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.

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 --name="My API Recipe" --folder=./build-folder --build-config=./build-folder/APIMATIC-BUILD.json

Flags:

  • --name=<value> : Name for the recipe.
  • --folder=<value> : Path to the build directory containing specs, content, and Build Config file. Defaults to the current working directory.
  • --build-config=<value> : Path to the APIMATIC-BUILD.json file. Defaults to the APIMATIC-BUILD.json file in the build directory provided by the --folder flag if not provided.

You can read more about API Recipes here.

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 --auth-key=YOUR_API_KEY
apimatic api:validate --url=https://petstore.swagger.io/v2/swagger.json --auth-key=YOUR_API_KEY

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> : Can be provided to 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 --destination=./output --force --auth-key=YOUR_API_KEY
apimatic api:transform --format=RAML --url="https://petstore.swagger.io/v2/swagger.json" --destination=./output --force --auth-key=YOUR_API_KEY

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> : Can be provided to 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 --platform=python --file=./specs/sample.json --destination=./output --force --zip --auth-key=YOUR_API_KEY
apimatic sdk:generate --platform=java --url="https://petstore.swagger.io/v2/swagger.json" --destination=./output --force --zip --auth-key=YOUR_API_KEY

Flags:

  • --platform=<value> : (required) Language platform for SDK. Run the command with the --help flag to see all options available.
  • --file=<value> : Path to the API specification to generate SDKs for.
  • --url=<value> : URL to the API specification to generate SDKs for. Can be used in place of the --file option if the API specification is publicly available.
  • --destination=<value> : Directory to download the generated SDK to. Defaults to ./.
  • --force, -f : Overwrite if an SDK already exists in the destination.
  • --zip : Download the generated SDK as a .zip archive.
  • --auth-key=<value> : Can be provided to override current authentication state with an authentication key.

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 --auth-key=YOUR_API_KEY

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.