GitClone CLI

Command-line client for the GitClone developer platform. Use it to stage and commit files, work with branches, inspect changes, and manage pull requests from a terminal.

• Web app: gitclone-by-nauman.vercel.app
• npm package: gitclone-by-nauman
• Source and issues: GitHub-Clone

Requirements

• Node.js 20 or newer
• A GitClone account
• A repository created in the GitClone web app

Installation

Install the CLI globally from npm:

npm install --global gitclone-by-nauman

Confirm that it is available:

gitclone --version
gitclone --help

The npm package is named gitclone-by-nauman, while the installed terminal command is gitclone.

Quick start

1. Sign in and obtain a token

Version 1.0.x accepts a GitClone JWT during init or clone. In PowerShell, the following prompts for your credentials and signs in without placing your password directly in the command history:

$credential = Get-Credential
$body = @{
  login = $credential.UserName
  password = $credential.GetNetworkCredential().Password
} | ConvertTo-Json

$session = Invoke-RestMethod `
  -Method Post `
  -Uri "https://github-clone-api-o3c7.onrender.com/api/auth/login" `
  -ContentType "application/json" `
  -Body $body

Use your GitClone username or email in the credential prompt. The production API runs on Render's free tier, so its first response after inactivity can take up to about a minute.

2. Connect a local folder

Create or open the matching repository in the GitClone web app, then run this inside your local project folder:

gitclone init `
  --api https://github-clone-api-o3c7.onrender.com/api `
  --owner YOUR_USERNAME `
  --repo YOUR_REPOSITORY `
  --token $session.token

This creates .gitclone.json in the current folder and connects it to the remote repository.

3. Stage and commit files

gitclone stage .
gitclone status
gitclone commit -m "Initial commit"
gitclone log --oneline

Clone an existing repository

Clone into a new directory with an owner/repository identifier:

gitclone clone YOUR_USERNAME/YOUR_REPOSITORY `
  --api https://github-clone-api-o3c7.onrender.com/api `
  --token $session.token

Useful clone options:

gitclone clone owner/repo --api API_URL --token TOKEN --branch develop
gitclone clone owner/repo --api API_URL --token TOKEN --dir my-folder
gitclone clone owner/repo --api API_URL --token TOKEN --force

--force permits existing files in the target directory to be overwritten. Review the directory before using it.

Command reference

| Command | Purpose | | --- | --- | | gitclone init | Connect the current folder to a GitClone repository. | | gitclone clone <owner/repo> | Download a repository into a local folder. | | gitclone stage <paths..> | Add files or folders to the staging area. | | gitclone delete <path> | Stage a remote file for deletion. | | gitclone status | Show staged and working-tree changes. | | gitclone unstage <path> | Remove one file from the staging area. | | gitclone reset-stage | Clear all staged changes. | | gitclone commit -m <message> | Commit staged changes. | | gitclone branch [name] | List branches or create a branch. | | gitclone checkout [branch] | Switch branches. | | gitclone pull | Download the current remote branch. | | gitclone log | Show commit history. | | gitclone diff [file] | Compare local files with the remote branch. | | gitclone pr <action> [id] | List, create, inspect, close, reopen, or merge pull requests. | | gitclone merge <source> | Merge a source branch into the current branch. |

Run gitclone <command> --help for every option supported by a command.

Files and staging

Stage one file, several paths, or the current folder:

gitclone stage README.md
gitclone stage src package.json
gitclone stage . --branch main

Inspect or change the staging area:

gitclone status
gitclone unstage README.md
gitclone delete old-file.txt
gitclone reset-stage

Commit the staged changes:

gitclone commit --message "Document the CLI"

The CLI respects common entries in .gitignore and always excludes sensitive or generated paths such as .gitclone.json, .git, node_modules, .env, and build output.

Branches

# List branches
gitclone branch

# Create a branch from the current branch
gitclone branch feature/docs

# Create a branch from main and switch to it
gitclone checkout -b feature/docs --from main

# Switch branches
gitclone checkout main

# Delete a branch
gitclone branch --delete feature/docs

Pull the selected branch into the local folder:

gitclone pull --branch main

Use gitclone pull --force only when it is acceptable to overwrite conflicting local files.

History and differences

gitclone log
gitclone log --limit 10 --oneline
gitclone diff
gitclone diff src/index.js
gitclone diff --name-only
gitclone diff --summary

Pull requests and merging

Create a pull request:

gitclone pr create `
  --base main `
  --compare feature/docs `
  --title "Add CLI documentation" `
  --description "Documents installation and common workflows."

Manage pull requests:

gitclone pr list
gitclone pr list --status ALL
gitclone pr view PR_ID
gitclone pr close PR_ID
gitclone pr reopen PR_ID
gitclone pr merge PR_ID

Merge a branch directly into the current branch:

gitclone merge feature/docs
gitclone merge feature/docs --base main --delete-source

The merge command pulls the merged base branch by default. Pass --no-pull to skip that download. --force bypasses reported conflict detection and should be used only after reviewing the changes.

Configuration and security

gitclone init creates a .gitclone.json file similar to this:

{
  "apiUrl": "https://github-clone-api-o3c7.onrender.com/api",
  "owner": "your-username",
  "repo": "your-repository",
  "token": "<JWT>",
  "branch": "main",
  "repoId": "<repository-id>"
}

The token is stored locally as plain text. Treat .gitclone.json like a password:

• Never commit, publish, paste, or share it.
• Keep .gitclone.json in .gitignore.
• Re-run gitclone init with a new token if the session expires.
• Do not use a production token with an untrusted API URL.

The CLI automatically excludes .gitclone.json from staging, but other tools may not.

Troubleshooting

gitclone is not recognized

Restart the terminal after installation, then verify npm's global binary location:

npm prefix --global
npm list --global gitclone-by-nauman

Reinstall if necessary:

npm uninstall --global gitclone-by-nauman
npm install --global gitclone-by-nauman

Missing .gitclone.json

Run gitclone init from the project folder, or use gitclone clone to create a configured local copy.

401 Unauthorized or an expired token

Sign in again to obtain a new token, then run gitclone init again with the same owner and repository.

The first production request is slow

The API uses a free Render service that sleeps during inactivity. Allow up to about a minute for the first request and retry once it is awake.

Local files would be overwritten

Review or back up the affected files. Use --force only when replacing them is intentional.

Local CLI development

From the repository root:

cd gitclone-cli
npm ci
npm link
gitclone --help

Preview the files that npm will publish:

npm pack --dry-run

Uninstall

npm uninstall --global gitclone-by-nauman

License

ISC © 2026 Nauman Naikwade