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, adopts an existing API specification if your repository has one, 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.
Adopts an existing OpenAPI, Swagger, or AsyncAPI specification. If postman init doesn’t find any specifications, the SKILL.md guides your AI agent to build one from your code.
Installs the agent skills from the Postman skills repository. This gives AI agents the information they need to build and test the API with the Postman CLI. To learn more, see Agent skills.
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.
If you’re not signed in, it creates a temporary guest workspace and connects your project to it. This lets you set up a cloud-backed project without signing in first, then keep working as a guest, such as creating collections and monitors in the Postman Cloud. Run postman signup later to claim the workspace and keep your work.

When it finishes, postman init prints the files it created as a file tree, so you can see the project’s layout at a glance. Machine-readable output (--json) is unchanged.

Claiming a guest workspace works only through postman signup. If you sign in to an existing Postman account instead, the guest workspace isn’t copied to it.

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.

--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.

Agent skills

The postman init command fetches the latest agent skills from the Postman skills repository each time you run the command. It installs them under postman/skills/, one folder per skill, each with its own SKILL.md, along with a root AGENTS.md file that points AI agents to them.

To fetch the skills from a different origin, set the POSTMAN_SKILLS_URL environment variable.

To check whether an existing project’s skills are current and update them, use the postman skills commands.

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 and Develop with a coding agent using Native Git.