> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://learning.postman.com/llms.txt. # Init command This topic covers the `postman init` command for the [Postman CLI](/docs/postman-cli/postman-cli-overview/). ## `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](/docs/use/native-git/overview/) 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`](/docs/postman-cli/postman-cli-workspace/#postman-workspace-create), then commit `.postman/resources.yaml` so your CI builds inherit the connection. ### Usage ```bash postman init [path] [options] ``` **`[path]`** The path to the repository to set up. Defaults to the current directory. --- ### Options **`--spec `** Specifies which specification is authoritative when more than one could apply. --- **`--no-seed`** Don't derive a specification from your source code. --- **`--visibility `** 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 ```bash # 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`](/docs/postman-cli/postman-cli-workspace/#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](/docs/use/native-git/overview/).