@apimatic/cli
The official CLI for APIMatic.
Requirements
Node.js 22.14 or newer, for every command. Install with @2: on an older Node, npm skips a
latest release whose engines it fails and a bare @apimatic/cli silently installs CLI v1.
With @2 npm only warns, so the install succeeds and the CLI then refuses to run, naming the
version it found.
Git 2.38 or newer on your PATH, for sdk generate and sdk publish to keep your changes to a
generated SDK across regenerations. Without it the commands still generate, and warn that your
customizations will not persist.
Getting Started
To get started with APIMatic's CLI using a step by step wizard, run the following command:
$ apimatic quickstart
Usage
$ npm install -g @apimatic/cli@2
$ apimatic COMMAND
running command...
$ apimatic --help [COMMAND]
USAGE
$ apimatic COMMAND
...
Commands
apimatic api transformapimatic api validateapimatic auth loginapimatic auth logoutapimatic auth statusapimatic autocomplete [SHELL]apimatic help [COMMAND]apimatic plugin generateapimatic plugin publishapimatic portal generateapimatic portal serveapimatic publishing profile listapimatic quickstartapimatic sdk generateapimatic sdk publish
apimatic api transform
Transform API specifications between different formats
USAGE
$ apimatic api transform --format
apimatic|wadl2009|wsdl|swagger10|swagger20|swaggeryaml|oas3|openapi3yaml|apiblueprint|raml|raml10|postman10|postman2
0|graphqlschema [--file <value>] [--url <value>] [-d <value>] [-f] [-k <value>]
FLAGS
-d, --destination=<value> [default: ./] Directory to save the transformed file to
-f, --force overwrite changes without asking for user consent.
-k, --auth-key=<value> override current authentication state with an authentication key.
--file=<value> Path to the API specification file to transform
--format=<option> (required) Specification format to transform API specification into
<options: apimatic|wadl2009|wsdl|swagger10|swagger20|swaggeryaml|oas3|openapi3yaml|apibluep
rint|raml|raml10|postman10|postman20|graphqlschema>
--url=<value> URL to the API specification file to transform (publicly accessible)
DESCRIPTION
Transform API specifications between different formats
Transform API specifications from one format to another.
Supports multiple formats including OpenAPI/Swagger, RAML, WSDL, and Postman Collections.
EXAMPLES
apimatic api transform --format=openapi3yaml --file=./specs/sample.json --destination=./
apimatic api transform --format=raml --url="https://petstore.swagger.io/v2/swagger.json" --destination=./
See code: src/commands/api/transform.ts
apimatic api validate
Validate API specification for syntactic and semantic correctness
USAGE
$ apimatic api validate [--file <value> | --url <value> | -i <value>] [-k <value>]
FLAGS
-i, --input=<value> [default: ./] path to the parent directory containing the 'src' directory, which includes API
specifications and configuration files.
-k, --auth-key=<value> override current authentication state with an authentication key.
--file=<value> Path to the API specification file to validate
--url=<value> URL to the API specification file to validate (publicly accessible)
DESCRIPTION
Validate API specification for syntactic and semantic correctness
Validate the API specification in your 'src/spec' directory, or the one --file or --url points to, to ensure it
adheres to syntactic and semantic standards.
EXAMPLES
apimatic api validate
apimatic api validate --input=./
apimatic api validate --file=./specs/sample.json
apimatic api validate --url="https://petstore.swagger.io/v2/swagger.json"
See code: src/commands/api/validate.ts
apimatic auth login
Login to your APIMatic account
USAGE
$ apimatic auth login [-k <value>]
FLAGS
-k, --auth-key=<value> Sets authentication key for all commands.
DESCRIPTION
Login to your APIMatic account
Login using your APIMatic credentials or an API Key
EXAMPLES
apimatic auth login
apimatic auth login --auth-key={api-key}
See code: src/commands/auth/login.ts
apimatic auth logout
Clears the local login credentials.
USAGE
$ apimatic auth logout
DESCRIPTION
Clears the local login credentials.
Clears the local login credentials. This will also clear any cached credentials from the CLI.
EXAMPLES
apimatic auth logout
See code: src/commands/auth/logout.ts
apimatic auth status
View the currently logged in user.
USAGE
$ apimatic auth status
DESCRIPTION
View the currently logged in user.
EXAMPLES
apimatic auth status
See code: src/commands/auth/status.ts
apimatic autocomplete [SHELL]
Display autocomplete installation instructions.
USAGE
$ apimatic autocomplete [SHELL] [-r]
ARGUMENTS
[SHELL] (zsh|bash|powershell) Shell type
FLAGS
-r, --refresh-cache Refresh cache (ignores displaying instructions)
DESCRIPTION
Display autocomplete installation instructions.
EXAMPLES
$ apimatic autocomplete
$ apimatic autocomplete bash
$ apimatic autocomplete zsh
$ apimatic autocomplete powershell
$ apimatic autocomplete --refresh-cache
See code: @oclif/plugin-autocomplete
apimatic help [COMMAND]
Display help for apimatic.
USAGE
$ apimatic help [COMMAND...] [-n]
ARGUMENTS
[COMMAND...] Command to show help for.
FLAGS
-n, --nested-commands Include all nested commands in the output.
DESCRIPTION
Display help for apimatic.
See code: @oclif/plugin-help
apimatic plugin generate
Generate a context plugin for your SDKs.
USAGE
$ apimatic plugin generate [-i <value>] [-d <value>] [-f] [-k <value>]
FLAGS
-d, --destination=<value> [default: <input>/plugin] path where the plugin will be generated.
-f, --force overwrite changes without asking for user consent.
-i, --input=<value> [default: ./] path to the parent directory containing the 'src' directory, which includes
API specifications and configuration files.
-k, --auth-key=<value> override current authentication state with an authentication key.
DESCRIPTION
Generate a context plugin for your SDKs.
Generate a context plugin that teaches an AI coding assistant how to use your SDKs. Requires an input directory
containing a `src` directory with your API specification — `apimatic.json` is created if it is not there. It asks for
the plugin's name on the first run, and for its languages only when `apimatic.json` records none (`sdk publish`
records them). Later runs read both from `apimatic.json` without asking.
EXAMPLES
apimatic plugin generate
apimatic plugin generate --input="./" --destination="./plugin"
See code: src/commands/plugin/generate.ts
apimatic plugin publish
Print the git commands for publishing your context plugin to GitHub.
USAGE
$ apimatic plugin publish [-i <value>] [-d <value>]
FLAGS
-d, --destination=<value> [default: <input>/plugin] path where the plugin was generated.
-i, --input=<value> [default: ./] path to the parent directory containing the 'src' directory, which includes
API specifications and configuration files.
DESCRIPTION
Print the git commands for publishing your context plugin to GitHub.
Print the commands that publish a generated context plugin to a GitHub repository. The commands are printed for you to
run — this command never touches your repository.
EXAMPLES
apimatic plugin publish
apimatic plugin publish --input="./" --destination="./plugin"
See code: src/commands/plugin/publish.ts
apimatic portal generate
Generate a static API Documentation Portal.
USAGE
$ apimatic portal generate [--zip] [-i <value>] [-d <value>] [-f] [-k <value>]
FLAGS
-d, --destination=<value> [default: <input>/portal] path where the portal will be generated.
-f, --force overwrite changes without asking for user consent.
-i, --input=<value> [default: ./] path to the parent directory containing the 'src' directory, which includes
API specifications and configuration files.
-k, --auth-key=<value> override current authentication state with an authentication key.
--zip write the generated portal as a .zip archive.
DESCRIPTION
Generate a static API Documentation Portal.
Builds a documentation portal from the OpenAPI documents and Markdown pages in your 'src' directory.
Each OpenAPI document at the top of 'src/spec' gets a section of the API reference, and the SDKs are built from one of
them. To build the SDKs from several, put each in a folder of its own and set 'MergeConfiguration.MergeApis' to true
in an 'APIMATIC-META.json' beside the folders; each folder then gets a section.
The portal is built on your machine and written as static files for any static host, served at its root or, when
'portal.site.url' has a path such as 'https://example.com/docs', at that path. Configure it with 'src/apimatic.json',
whose 'languages' block gives the portal a page for each SDK language, and whose 'plugin' block, or a 'pluginUrl' in
its 'portal' block for a plugin hosted elsewhere, a page for the context plugin.
EXAMPLES
apimatic portal generate
apimatic portal generate --input=./ --destination=./portal
apimatic portal generate --zip
See code: src/commands/portal/generate.ts
apimatic portal serve
Preview your API Documentation Portal with live reload.
USAGE
$ apimatic portal serve [-p 23513] [-o] [-i <value>] [-k <value>]
FLAGS
-i, --input=<value> [default: ./] path to the parent directory containing the 'src' directory, which includes API
specifications and configuration files.
-k, --auth-key=<value> override current authentication state with an authentication key.
-o, --open open the portal in the default browser.
-p, --port=23513 [default: 23513] port to serve the portal on.
DESCRIPTION
Preview your API Documentation Portal with live reload.
Serves the portal described by 'src/apimatic.json' from your machine, reloading the browser as you edit the Markdown
pages in 'src/content', reorder them in a 'nav.json', edit the documents in 'src/spec', or change the 'portal',
'languages' or 'plugin' block of 'apimatic.json'.
Adding a language or a 'plugin' block, adding or removing a page in 'src/content', creating 'src/static', changing
which documents are in 'src/spec' or which folders its 'APIMATIC-META.json' merges, or changing the path in
'portal.site.url', needs the preview restarted.
Nothing is written to disk; run 'apimatic portal generate' to produce the static files.
EXAMPLES
apimatic portal serve
apimatic portal serve --input=./ --port=23513 --open
See code: src/commands/portal/serve.ts
apimatic publishing profile list
List all publishing profiles
USAGE
$ apimatic publishing profile list
DESCRIPTION
List all publishing profiles
Display all publishing profiles associated with your account, including each profile's name, ID and enabled languages.
EXAMPLES
apimatic publishing profile list
See code: src/commands/publishing/profile/list.ts
apimatic quickstart
Create your API Documentation Portal, SDKs and Context Plugins.
USAGE
$ apimatic quickstart
DESCRIPTION
Create your API Documentation Portal, SDKs and Context Plugins.
Point the CLI at your API specification and it builds a documentation portal, SDKs, and a context plugin that teaches
an AI coding assistant to use them.
EXAMPLES
apimatic quickstart
See code: src/commands/quickstart.ts
apimatic sdk generate
Generate an SDK for your API
USAGE
$ apimatic sdk generate -l csharp|java|php|python|ruby|typescript|go [-d <value>] [--stability stable|beta]
[--git-init] [-i <value>] [-f] [-k <value>]
FLAGS
-d, --destination=<value> [default: <input>/sdk/<language>] directory the SDK is generated into
-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.
-i, --input=<value> [default: ./] path to the parent directory containing the 'src' directory, which includes
API specifications and configuration files.
-k, --auth-key=<value> override current authentication state with an authentication key.
-l, --language=<option> (required) Programming language for SDK generation
<options: csharp|java|php|python|ruby|typescript|go>
--git-init Track the SDK directory with its own git repository so your customizations survive
regeneration.
--stability=<option> Stability level of the generated SDK. Defaults to the level the language offers.
<options: stable|beta>
DESCRIPTION
Generate an SDK for your API
Generate a Software Development Kit (SDK) from an API specification.
C#, TypeScript and Python are available; Java, Ruby, Go and PHP are coming soon.
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).
EXAMPLES
apimatic sdk generate --language=typescript
apimatic sdk generate --language=csharp --input=./
apimatic sdk generate --language=python --destination=./my-python-sdk
See code: src/commands/sdk/generate.ts
apimatic sdk publish
Generate and publish an SDK to a package registry and/or source repository
USAGE
$ apimatic sdk publish [-p <value>] [-v <value>] [-d <value>] [-l csharp|java|php|python|ruby|typescript|go]
[-f] [-i <value>] [--publish-type package|sourcecode...] [--dry-run] [--stability stable|beta] [--git-init]
FLAGS
-d, --destination=<value> [default: <input>/sdk/<language>] path where the sdk will be generated.
-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.
-i, --input=<value> [default: ./] path to the parent directory containing the 'src' directory, which
includes API specifications and configuration files.
-l, --language=<option> Language of the SDK to generate and publish.
<options: csharp|java|php|python|ruby|typescript|go>
-p, --profile-id=<value> Id of the publishing profile to use.
-v, --version=<value> Semantic version of the SDK to publish (e.g. 1.0.0).
--dry-run Generate the SDK locally for review without publishing.
--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.
--publish-type=<option>... One or more publishing targets: 'package' for a package registry, 'sourcecode' for a
git repository.
<options: package|sourcecode>
--stability=<option> Stability level of the generated SDK. Defaults to the level the language offers.
<options: stable|beta>
DESCRIPTION
Generate and publish an SDK to a package registry and/or source repository
Generate and publish an SDK using a publishing profile configured in the APIMatic App. Requires an input directory
containing the API specification. 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.
EXAMPLES
apimatic sdk publish
apimatic sdk publish --profile-id=a1b2c3d4e5f6a1b2c3d4e5f6 --language=typescript --version=1.0.0 --publish-type=package --publish-type=sourcecode
apimatic sdk publish --profile-id=b2c3d4e5f6a1b2c3d4e5f6a1 --language=csharp --version=2.0.0 --publish-type=sourcecode
apimatic sdk publish --profile-id=c3d4e5f6a1b2c3d4e5f6a1b2 --language=python --version=1.0.0 --publish-type=package --dry-run
See code: src/commands/sdk/publish.ts