microgit-cli

microgit — your own git server — clone, push, host.

A small command line client for the microgit server. It keeps the API session in a local config file, creates and deletes repositories, and wraps the usual git commands so push/pull work with the account credentials.

It is a separate TypeScript project with no runtime dependencies (Node's built-in fetch, readline and git are enough).

Install

npm install -g microgit-cli

Without a global install, run the built entry point directly:

node src/index.js --help

Interactive shell

Run microgit with no arguments (or microgit shell) to open the shell:

  ● ━━━ ●
    ┣━━━ ●   microgit-cli • gitserver  v0.1.0
    ┗━━━ ●   your own git server — clone, push, host

  # server   http://{HOST_NAME}:{PORT}
  # account  alice · 7d left

  ✓ ready · type help to list the commands
  # one-shot microgit --help

alice@microgit:~/repos$ new app

Starting the shell clears the screen and the scrollback first, so the banner is the only thing on the page. The prompt shows the signed-in account and the current folder. Commands are the same words as the one-shot CLI, and the shell adds:

Errors never close the shell. A command that asks something (login, commit, delete, new) asks inside the same prompt.

Quick start

# 1. Point the CLI at the server and sign in. Use the host and port the
#    server actually listens on, or its domain behind a reverse proxy.
microgit login --url http://{HOST_NAME}:{PORT}

# 2. Create a repository and a local checkout with a first commit,
#    then push it.
microgit new app --init

# 3. Work as usual; commit also pushes.
cd app
echo "hello" > hello.txt
microgit commit -m "Add hello.txt"

# 4. Check the session or list repositories.
microgit whoami
microgit list

Signing in again reuses a valid stored session, so the username and password are only asked for once. Add --force to sign in as another account.

Commands

Every command accepts -h / --help. Commands that print API data also accept --json where it makes sense (whoami, list, new, delete, clone, login, register, logout, config).

Creating repositories

Without --private or --public the CLI asks for the visibility, and Enter creates a public repository:

microgit new app                  # asks: public or private
microgit new secret --private
microgit new app --public
microgit new app --clone          # create it and clone the empty repository
microgit new app --init           # create it, README, first commit and push
microgit new app --init --dir ./projects/app

The request sent to the server is {"name":"app","private":false} (or true).

new prints the server's clone URL. Existing repositories are not an error: the API returns created: false and the CLI says it already exists.

Starting a local repository

microgit init is local only — it does not talk to the server:

microgit init app        # creates ./app, .git on main, empty README.md
microgit init            # initialise the current folder
microgit init --dir ./projects/app

It refuses to run inside an existing repository, and reuses the saved account name for user.name / user.email when git has none configured.

Deleting repositories

microgit delete app                 # asks for confirmation
microgit delete app --yes           # non-interactive
microgit delete bob/app --yes       # administrators can delete for another owner

Listing repositories

microgit list
microgit list --owner alice
microgit list --private --limit 20
microgit list --public --page 2 --json

Authentication and git credentials

The JSON API uses the session token returned by login. The CLI sends it as Authorization: Bearer <token> and stores it in the config file. Git uses HTTP Basic with the account username and password, not the API token.

For that reason login only stores the token by default. Add --save-password to also store the password, which makes push, pull, clone of a private repository and new --init work without another prompt:

microgit login --save-password

The password is stored in plain text in the config file. The file is created with mode 600 on Unix; on Windows the user profile permissions apply. If you do not want to store it, leave --save-password off and let git ask when it needs credentials, or set MICROGIT_PASSWORD for one command:

MICROGIT_PASSWORD='alicepass1' microgit push

Logging in again keeps a saved password when the username is unchanged; pass --forget-password to remove it.

The CLI passes credentials to git as an http.extraHeader, so they are not written into .git/config and are not part of the clone URL.

The server's message of the day, when it publishes one, is printed after login, register and whoami.

Config file

Default location: ~/.microgit/config.json. Use MICROGIT_CONFIG to point at a different file, for example one per server:

MICROGIT_CONFIG=~/.microgit/work.json microgit login --url https://git.example.com

The shell keeps its history next to it, in ~/.microgit/history.

Show it with:

microgit config
microgit config set url https://git.example.com
microgit config set username alice
microgit config unset password
microgit config clear

Environment variables override the file for one command:

Renaming the CLI

Package name, command name, banner, tagline, label, version, environment prefix and config folder all live in src/settings.ts. Change them there and update name / bin in package.json to match.

Domains

The server's domain / publicUrl setting changes the clone URL it returns. microgit clone and microgit new --init use that URL, so the name must resolve from the machine running the CLI. If the public domain is only reachable from outside, log in with the internal URL instead; the repository still works, but a domain configured on the server wins when it builds the clone URL.

Exit codes

• 0 success
• 1 expected failure (bad input, server error, git failure)

Errors are printed once without a stack trace. --json output is still the server's JSON (or, for whoami/config, a small object with the same fields).

Troubleshooting

• You are not signed in — run microgit login; the token expires after the server's sessionDays.
• login keeps signing in as the old account — the stored session is still valid; pass --force or run microgit logout first.
• Authentication failed on push — login --save-password, or set MICROGIT_PASSWORD; the username/password is your account, not the API token.
• No 'origin' remote — use microgit clone <owner/name> or add a remote with git.
• Directory is not empty — --clone/--init refuse to overwrite files; choose another --dir.
• Already a git repository — microgit init skips folders that already have .git.
• Server unreachable — pass --url or set MICROGIT_URL; check the server's host, port and reverse proxy.