Command line client for advanced developers

The Apiary CLI gem is a command line tool for developing and previewing API Blueprint documents locally. It can also be used for pushing updated documents to and fetching existing documents from

Many developers spend all of their time on the command line, and the goal of this tool is to make it where you spend more of your time there while writing your documentation.

This tool interfaces directly with the Apiary API (see the documentation).


The Apiary CLI tool is written in Ruby and can be installed with:

gem install apiaryio

The code is open sourced on GitHub apiaryio/apiary-client and is licensed under the MIT license. Feel free to fork and send pull requests with any features or bug fixes.

Getting Started

In order for this tool to communicate with Apiary, you will need to first generate an authentication key. You will also need to find out the specific name of your API with which you want to interact. If you want to use this tool only to preview locally, you can skip these steps.

Generating an Authentication Token

In order to fetch and publish documentation, you will need to generate an authentication token by going to Keep this token safe, because a token is like a password and will give anyone with this token access to fetch and publish to your documentation.


Just to reiterate, please keep your token safe, as it provides access to fetch and publish API Description documents.

Once you have generated a token, you’ll need to set it as an environment variable. The CLI tool will warn you in the event that you do not have this variable set.

export APIARY_API_KEY="<token>"

Finding the Name of Your API

For the purpose of fetching and publishing, you will need to get the name of your API documentation (designated as API_NAME throughout this documentation). To find out this out, click on Settings at the top of your documentation page, and you should see the name in the API Domain section.


You can view all of the available commands with the help command:

apiary help

Apiary CLI help

You can also get usage instructions and available commands for each command by including the command name after help. For example, to see the help for preview, use:

apiary help preview

Fetching Published Documentation

If you already have documentation on, you can fetch the API Description document (both API Blueprint and Swagger)

apiary fetch --api-name="<API_NAME>"

By default, this will fetch and print the contents of your API Description document to the console.


To specify an output file, use the --output flag.

apiary fetch --api-name="<API_NAME>" --output="apiary.apib"
# or
apiary fetch --api-name="<API_NAME>" --output="swagger.yaml"

The file extension for API Blueprint documents is .apib. This is useful for using the API Blueprint Sublime Text plugin, or for linking your documentation to GitHub (see Docs for GitHub Sync).

Previewing Documentation Locally

While working on the documentation locally, you can also preview what it would look like without sending to

apiary preview

This command looks for a file named apiary.apib or swagger.yaml in the current working directory, generates the static content, and opens your default browser to preview. It also validates your document and will let you know if there are any errors.


Your API Description Document should include host URL


To save this generated HTML in a file, you can use the --output flag.

apiary preview --output="docs.html"

Without this flag, the contents will be saved to a temporary file for previewing.


As stated, by default, the preview command is looking for apiary.apib or swagger.yaml in the current directory. If both files are present, apiary.apib is used. You can change the name and path with the --path flag.

apiary preview --path="/path/to/apiary.apib"
# or
apiary preview --path="/path/to/swagger.yaml"


If you’d rather not generate the file over and over, you can start up a server that can be refreshed after each change.

apiary preview --server


You can change the port of the server by adding the --port flag with the desired port number.

apiary preview --server --port=8080

The port parameter must be used with the --server flag.


By default, the Swagger API Description Document is expected to be in yaml format. You can process json document by adding the --json flag.

apiary preview --json


To reload API documentation in the browser when API Description Document has changed use the --watch flag.

apiary preview --watch

The watch command must be used with the --server flag to take effect.


By default, the default browser is opened with the preview command. You can specify a different browser with the --browser flag.

apiary preview --browser="safari"

Currently, the supported browsers are Chrome, Safari, and Firefox.

Publishing Changes to

Once you are ready to go live with the changes you’ve made, you can use the publish command to publish changes to This requires that you generate an authentication token, as mentioned above.

apiary publish --api-name="<API_NAME>"

This command is looking for a file named apiary.apib or swagger.yaml by default.


To change the path the publish command uses, use the --path flag.

apiary publish --path="/path/to/apiary.apib"
# or
apiary publish --path="/path/to/swagger.yaml"


If your documentation is linked up to GitHub, you can add a commit message when publishing to Apiary.

apiary publish --message="Made changes to documentation"


By default, the Swagger API Description Document is expected to be in yaml format. You can process json document by adding the --json flag. Document will be converted to yaml before publishing.

apiary publish --json

Using Apiary Style Guide

API style guide helps to adhere to basic API design patterns and conventions. ( pro plan is required )

apiary styleguide

This command looks for a file named apiary.apib or swagger.yaml, rules.json and functions.js in the current working directory and outputs the validation results.


Use the --fetch to fetch styleguide rules and functions set in your team from (Architect or Administrator role is required) It is saved to the rules.json and functions.js files in current directory.

--add, --functions, --rules

You can specify the paths to your API description and function and rules definitions if they are stored under different than default locations and names.

apiary styleguide --add=/path/to/the/api_description_definition --functions=/path/to/the/functions_definition --rules=/path/to/the/rules_definition`


By default only failed validations are displayed. Full result can be displayed by using --full-report parameter.

Was this page useful?
Thank you for the feedback!
What went wrong?