Init command

This topic covers the postman init command for the Postman CLI.

`postman init`

Use the postman init command to set up an AI-ready API project in your local repository. In a single step, it creates the Postman Native Git project structure, can generate a starting API specification from your code, and adds a SKILL.md that teaches AI agents how to build and test the API with the Postman CLI.

When you run postman init, it does the following:

Detects or creates the postman/ project structure and the .postman/resources.yaml configuration file. If the postman/ directory already contains source code, postman init stops without writing anything.
Adds a starting API specification. If your repository already has an OpenAPI, Swagger, or AsyncAPI specification, postman init adopts it. If not, and your app uses Flask, it derives a starting OpenAPI specification from your routes. If neither applies, it doesn’t add a specification.
Adds a SKILL.md guide under postman/skills/, along with a root AGENTS.md file that points to it, so AI agents know how to build and test the API with the Postman CLI.
If you’re signed in, it offers to create a new Postman workspace and connect your project to it. You can skip this step with --no-cloud.

In CI, postman init doesn’t create a workspace. In this case, create and connect the workspace locally with postman workspace create, then commit .postman/resources.yaml so your CI builds inherit the connection.

Usage

$ postman init [path] [options]

[path]

The path to the repository to set up. Defaults to the current directory.

Options

--spec <path>

Specifies which specification is authoritative when more than one could apply.

--no-seed

Don’t derive a specification from your source code.

--visibility <status>

Sets the visibility of the workspace postman init creates: personal (private to you) or team (shared with your team). If you omit it, postman init prompts you when it offers to create a workspace.

--no-cloud

Skips creating and connecting a workspace.

--dry-run

Reports what the command would do without writing anything.

--json

Prints the result of the run as JSON for AI agents to parse, instead of the human-readable report. The JSON includes the project layout, the specification postman init chose, and the changes it made. In this mode, postman init doesn’t create or connect a workspace.

--report-events

Sends postman init usage analytics to Postman. Requires signing in.

Examples

$ # Set up the current repository
$ postman init
$ 
$ # Preview what the command would do without writing anything
$ postman init --dry-run

Exit codes

The postman init command sets a process exit code so scripts, CI pipelines, and AI agents can act on the result. The code isn’t part of the command’s output. To read it, check $? in your shell after the run (for example, echo $?), or let CI use it, where a non-zero code fails the step.

Code	Meaning
`0`	Set up a new project, or adopted an existing one.
`1`	The command couldn’t run because of incorrect usage or an unexpected error.
`2`	More than one specification could be authoritative. Re-run with `--spec` to choose one.
`4`	Refused, and wrote nothing. Either the `postman/` directory contains source code, or a specification it was told to use (named in `.postman/resources.yaml` or passed with `--spec`) points to a missing file.
`5`	The local setup finished, but the workspace you requested with `--visibility` wasn’t created. Your files are already written, so don’t re-run `postman init`. Use `postman workspace create` to create and connect a new workspace.

In --json mode, the same code is also in the exitCode field of the output, along with a refusal field. For an agent, read those fields instead of matching messages on the console.

Learn more at Native Git workflows.