sync-postman/README.md

CLI tool to sync Postman collections with GitHub for free

# User Guide for the sync-postman CLI Tool

`sync-postman` is an open-source CLI tool designed to sync Postman collections and environments with GitHub. This allows teams to collaborate on Postman collections and environments securely and for free, without relying on paid Postman collaboration plans. Your API keys and credentials remain on your local machine, ensuring complete security and privacy.



## Features

- **Push Postman Collections and Environments to GitHub:**
  Automatically sync your Postman data to a GitHub repository for version control and team collaboration.

- **Pull Collections and Environments from GitHub:**
  Fetch collections and environments from GitHub to Postman, ensuring all team members are working with the latest updates.

- **Collaborative Workflow:**
  Use GitHub's centralized repository to enable seamless collaboration among team members.

- **Custom Branch Support:**
  Specify branches for pushing and pulling collections, making it ideal for workflows involving feature branches.

- **Hard Pull for Fresh Sync:**
  Replace all Postman collections in your workspace with data from GitHub for a clean slate.

- **Secure by Design:**
  API keys and tokens are stored only on your local machine, ensuring maximum security.

- **Configurable Setup:**
  Customize your Postman and GitHub integration with an easy setup process.


## Prerequisites

1. **GitHub Repository**:
   - Create a GitHub repository for your team to store and manage Postman collections.
   - Add your team members as collaborators to this repository.

2. **GitHub Personal Access Token**:
   - Generate a GitHub token with **full repository access**.
   - [Learn how to create a GitHub token here](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token).

3. **Postman API Key**:
   - Obtain your Postman API key from your Postman account.
   - Visit the [Postman API keys page](https://web.postman.co/settings/me/api-keys) to generate a key.

4. **Node.js**:
   - Download and install Node.js from [nodejs.org](https://nodejs.org/) if you don’t already have it installed.

## Installation

Install the `sync-postman` package globally using npm:

```bash
  npm install -g sync-postman
```



## Initial Setup

Before using `sync-postman`, you need to configure it with your Postman and GitHub credentials:

```bash
  sync-postman setup
```

Follow the prompts to enter the following details:
- **Postman API Key:** Your Postman API key.
- **GitHub Repository URL:** The repository where collections and environments will be stored.
- **GitHub Token:** A personal access token for accessing the GitHub API.

### Reset a Specific Configuration
You can reset a specific configuration key (e.g., Postman API Key):

```bash
  sync-postman setup --reset POSTMAN_API_KEY
```

Following Keys for reset configs - 
`POSTMAN_API_KEY`, `GITHUB_REPO`, `GITHUB_TOKEN`

## Usage

### 1. Push Postman Collections and Environments to GitHub

```bash
  sync-postman push
```

This command pushes your current Postman collections and environments to the specified GitHub repository. By default:
- A new branch is created with a timestamp.
- The main branch (`main`) is used as the source branch.

#### Optional Arguments:
- `--branchName <branchName>`: Specify a custom branch name for the push.
- `--sourceBranch <sourceBranch>`: Specify the source branch (default is `main`).

**Example:**

```bash
  sync-postman push --branchName feature-sync --sourceBranch dev
```

### 2. Pull Collections and Environments from GitHub

```bash
  sync-postman pull
```

This command pulls collections and environments from GitHub and updates them in Postman.

#### Optional Arguments:
- `--hard`: Perform a hard pull, replacing all Postman collections with GitHub data.
- `--branch <branchName>`: Specify the branch to pull data from (default is `main`).

**Example:**

```bash
  sync-postman pull --hard --branch feature-sync
```


### 3. Check Configuration


```bash
  sync-postman check-config
```

Displays the current configuration details.


## Safe Workflow with Pull Requests

This npm package uses a **pull request (PR) workflow** to ensure safety when syncing collections and environments. Instead of directly pushing changes to the main branch, the package creates a new branch and opens a pull request. This approach offers the following benefits:

- **Review Changes:** Easily track what has changed in the collections or environments before merging.
- **Prevent Overwriting:** Avoid accidental overwrites of the main branch, preserving the integrity of existing collections and environments.
- **Collaborate Seamlessly:** Enable team members to review, approve, or comment on updates via GitHub's PR system.

By following this approach, the package ensures a controlled and transparent workflow, making it ideal for collaborative teams.



## Workflow

1. **Set Up Configuration:**
   Use the `sync-postman setup` command to configure the CLI with Postman and GitHub credentials.

2. **Push Collections to GitHub:**
   Use the `sync-postman push` command to sync your Postman collections and environments to GitHub.

3. **Collaborate via GitHub:**
   Share the GitHub repository with your team. Team members can pull the latest collections using the `sync-postman pull` command.

4. **Pull Updates:**
   Use the `sync-postman pull` command to fetch updates from GitHub and sync them to your Postman workspace.

5. **Hard Pull (Optional):**
   Use `sync-postman pull --hard` to replace all existing collections in Postman with GitHub data.



## Security

- **Local Configuration:** All sensitive information (Postman API Key, GitHub Token) is stored only on your local machine in the `.sync-postman-config.json` file located in your home directory.
- **No External Sharing:** Your credentials are never shared or transmitted outside your local environment.



## Example Scenarios

### Collaborative Team Workflow

1. Alice sets up `sync-postman` and pushes her collections to a shared GitHub repository.
2. Bob pulls the collections from GitHub using `sync-postman pull` and works on updates.
3. Bob pushes his changes back to GitHub using `sync-postman push`.
4. Alice pulls Bob's updates using `sync-postman pull`.




## License

This project is licensed under the [MIT License](LICENSE).

---