APIGit CLI

apigit is the command line for APIGit. It checks OpenAPI files on your machine or in CI, and it publishes API documents and mock servers from the repositories you keep on APIGit.


npm install -g @apigit/cli
apigit lint openapi.yaml

You can also run any command without installing: npx @apigit/cli lint openapi.yaml. Node.js 20 or later is needed. The CLI is free to use (MIT license) and sends no telemetry.

Check a file, no account needed

These commands work offline.

Command	What it does
`apigit lint openapi.yaml`	Lints the file with the same rule sets as the APIGit editor.
`apigit score openapi.yaml`	Scores how ready the API description is for AI agents, from 0 to 100, with a line per rule.
`apigit bundle openapi.yaml -o dist/openapi.yaml`	Writes one file with every external `$ref` resolved.
`apigit diff main HEAD openapi.yaml`	Lists what changed between two commits, branches or tags (or two files), with the changes that can break a client first.
`apigit breaking main HEAD openapi.yaml`	Lists only the breaking changes and exits 1 when there is one.
`apigit preview openapi.yaml`	Serves a local page of the file on your machine, re-read on every reload.

Rule sets

lint uses, in this order: the file given with --ruleset, the built-in set given with --builtin, a .spectral.yaml in the working directory, then the built-in oas-best-practice.

Built-in	Checks
`oas-best-practice`	OpenAPI best practice (the editor’s default)
`owasp-top10`	OWASP API Security Top 10
`url-guideline`	URL versioning style
`document`	Documentation quality

A rule set file is a Spectral rule set, the format you edit under API Governance in APIGit.


apigit auth login
apigit auth status

apigit auth login prints a short code and opens a page in your browser. Check that the page shows the same code and click Authorize: the CLI is then signed in. The token it received is listed under Settings › Personal Access Token, where you can delete it (Personal access tokens).

On a machine without a browser, create a token under Settings › Personal Access Token, choose CLI and automation, and pipe it in:


echo "$TOKEN" | apigit auth login --with-token

A “Git and repository API” token also works for documents and mock servers. The “CLI and automation” kind adds what apigit plan and organization rules read.

Publish documents and mock servers

Commit and push with git first: a publish uses a commit that is already on APIGit. Inside a clone the CLI finds the repository from the origin remote; elsewhere pass -R <owner>/<name>.


apigit doc publish --version 1.2.0 --access public     # the pushed HEAD
apigit doc list
apigit doc unpublish 1.2.0
 
apigit mock publish --name petstore --type spec --mount openapi.yaml
apigit mock call petstore /pets
apigit mock logs petstore
apigit mock delete petstore

--commit <sha> publishes a specific commit; --ref <branch> follows a branch, on plans that include it.
--dry-run prints what would be sent and sends nothing.
doc unpublish and mock delete ask for confirmation in a terminal and need --yes in a script.
apigit plan shows your plan, its limits and this month’s mock usage.

Use it in CI

Set APIGIT_TOKEN as a secret; the CLI reads it and stores nothing.


# GitHub Actions
- uses: actions/setup-node@v4
  with:
    node-version: 22
 
- run: npx @apigit/cli@0.1.1 lint openapi.yaml --format github-actions
 
- run: npx @apigit/cli@0.1.1 doc publish --version ${{ github.ref_name }} --commit ${{ github.sha }} --access public
  env:
    APIGIT_TOKEN: ${{ secrets.APIGIT_TOKEN }}

GitHub Actions without a stored secret

A repository admin says once which GitHub repository’s workflows may act on the APIGit repository:


apigit ci trust add my-github-org/petstore --ref refs/heads/main -R my-org/petstore

A job of that repository then signs in with the identity token GitHub issues to it:


permissions:
  id-token: write
  contents: read
steps:
  - uses: actions/checkout@v4
  - run: npx @apigit/cli@0.1.1 auth login --github-oidc -R my-org/petstore
  - run: npx @apigit/cli@0.1.1 doc publish --version v1 -R my-org/petstore

The login lasts one hour and works on that one repository: its files, branches, pull requests, documents and mock servers, not its settings, collaborators or share links. The first sign-in pins the trust to that GitHub repository’s id, so the same name registered again by someone else is refused. apigit ci trust list and apigit ci trust remove <id> show and end a trust. Without --ref, every branch and pull request of the GitHub repository can sign in.

On any other CI system run npx @apigit/cli … with the same arguments. lint also writes junit, sarif and json.

For pull requests:


apigit breaking origin/main HEAD openapi.yaml       # fail on a change that can break a client
apigit lint --org my-org --report-status            # add your organization's rule sets; post the commit status apigit/lint

--org adds the governance rule sets of your organization that apply to the repository. --report-status posts the result on the commit, and a branch protection rule can require it before a merge.

Exit codes

Code	Meaning
0	Success
1	The check failed: findings at or above `--fail-severity`, or a score below `--min`
2	Wrong arguments, or the command could not run
3	Not signed in, or not allowed
4	Not found
5	Conflict
6	Plan limit reached
7	Network or server trouble; safe to retry

Upgrade


apigit upgrade            # install the latest version
apigit upgrade --check    # only report the installed and the latest version

apigit upgrade runs the package manager that installed the CLI. For a project dependency or an npx run it prints the command to run instead. On a terminal the CLI checks once a day for a newer version and prints one line when there is one; it stays silent in CI, in a pipe and with --json, and APIGIT_NO_UPDATE_CHECK=1 turns the check off. The CLI never updates itself.

To make a repository state the version it expects, add cliVersion: ">=0.1.0" (or an exact version) to apigit.yaml. In CI, pin the version: npx @apigit/cli@0.1.1 ….

Use it with an AI agent


apigit skills install

This copies an Agent Skill that teaches coding agents the CLI into .agents/skills/ (and .claude/skills/ when that directory exists). It prints each path and writes nothing else. --json on any command prints one JSON value, and apigit context lists every command and option as JSON.

Connect an agent with MCP


apigit agent setup                    # Claude Code; or --client cursor, --client vscode

This adds an APIGit server to the agent’s configuration in your project. The agent starts apigit mcp, which uses your apigit auth login, so no token is written to a file. The server gives the agent:

tools on the OpenAPI files in your working directory that need no network: lint, bundle, outline, one operation
read-only tools on your APIGit account: repositories, OpenAPI files at any branch, tag or commit, the changes between two of them, pull requests, published documents, mock servers and their request logs, and your organization’s rule sets

Set up this way, nothing can change a repository, a document or a mock. apigit agent setup --write adds the tools that do: create a branch, commit or patch files on a branch, open a pull request, publish or remove a document version or a mock. They never write to the default branch or a protected branch, never make a document public and never turn a mock’s access control off; a person merges and does those in the application.

An agent host that connects to a URL, such as a chat application, uses the APIGit MCP server directly: that page lists every tool, how each kind of host signs in and how to disconnect one.

To let an agent read a published API document (its llms.txt, Markdown pages and MCP server), see Use a published API document with AI agents. apigit doc view <version> prints those addresses.