Postman CLI init command `(postman init)`

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. Decline the prompt to skip this step, or run with --json and no --visibility to skip it non-interactively.
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. With --yes, it defaults to personal instead of prompting.

-y, --yes

Accepts the default for every question instead of asking or stopping. A workspace is created and bound as --visibility personal unless you set another value, or a guest session if you aren’t signed in. In CI, no workspace is created either way. When more than one specification could be authoritative, the specification is left unbound unless --spec names one.

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

--no-fetch

Uses the skills bundled with the Postman CLI instead of fetching the latest skills over HTTPS. By default, postman init fetches the latest skills and falls back to the bundled copy if the fetch is unreachable, so it still works offline. Use --no-fetch to skip fetching.

--report-events

Reports postman init events to the API Catalog and Application Inventory ingestion pipelines. Reporting is off by default. Pass --report-events to turn it on. Requires signing in with postman login or setting the POSTMAN_API_KEY environment variable.

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
# Accept every default, including a personal workspace
postman init --yes
# Accept every default, with a team workspace instead of personal
postman init --yes --visibility team

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.