Gent CLI

Gent is a Git-like version control CLI with cloud authentication and remote sync.

Global API URL:

https://gent-api.onrender.com

The CLI is configured in src/utils/constants.js to use that deployed API. Do not use a local API URL for normal CLI work.

Requirements

• Node.js 18 or newer
• Internet access to https://gent-api.onrender.com (only for remote/auth commands; local commands work offline)
• A Gent account, created with gent register

What makes Gent "smart"

Beyond a faithful git-like workflow, Gent adds:

• diff3 three-way merge with language-aware auto-resolution (JSON key merge, import unioning) that resolves more conflicts correctly and never merges unsafely.
• gent undo / gent redo — a one-command safety net over an operation journal (friendlier than git reflog).
• gent resolve — an interactive conflict resolver (ours / theirs / both / edit / AI).
• gent summary — a repository health dashboard, plus gent log --graph.
• Optional AI (gent commit --ai, gent explain, gent summary --ai, AI option in gent resolve) — off by default, enabled with ANTHROPIC_API_KEY.

See docs/COMMANDS.md for the full reference and docs/ALGORITHMS.md for how the engines work.

Install

From npm:

npm install -g gent-cli
gent --help

From this repository:

cd apps/Cli
npm install
npm link
gent --help

Run without linking:

node src/index.js --help

Full Step-by-Step Workflow

1. Create an account

Interactive:

gent register

Non-interactive:

gent register \
  -e [email protected] \
  -p StrongPass123! \
  --password-confirm StrongPass123! \
  --first-name YourFirstName \
  --last-name YourLastName

After registration, the CLI stores your encrypted auth tokens in:

~/.gent/auth.json

2. Log in

Interactive:

gent login

Non-interactive:

gent login -e [email protected] -p StrongPass123!

3. Confirm the logged-in user

gent whoami

Expected result: your email, name, account ID, joined date, and active status.

4. Create a project folder

mkdir my-project
cd my-project

5. Initialize a Gent repository

gent init

This creates:

.gent/
.gentignore

The .gent directory stores local commits, objects, branches, tags, staging data, and config.

6. Create a remote repository

gent repos --create my-project --description "My first Gent repository"

Expected output includes a remote path like:

/api/repos/2/my-project

Keep this path. It is not a local URL. The CLI combines it with the global API URL:

https://gent-api.onrender.com/api/repos/2/my-project

7. Link the local repo to the remote repo

Use the /api/repos/<owner_id>/<repo_name> path from the previous command:

gent remote add origin /api/repos/2/my-project

If the current folder is not initialized yet, gent remote add initializes .gent first, then adds the remote. You can still run gent init yourself before this step if you prefer the explicit flow.

Check it:

gent remote -v

Expected output:

origin -> /api/repos/2/my-project

8. Create files

echo "Hello Gent" > README.md
mkdir src
echo "console.log('hello')" > src/index.js

9. Check status

gent status

Expected result: untracked files.

10. Stage files

Stage specific files:

gent add README.md src/index.js

Or stage everything:

gent add .

11. Review staged changes

gent diff --staged

Short summary:

gent diff --staged --stat

12. Commit

gent commit -m "Initial commit"

Expected result: a commit hash, author, date, tree hash, and file stats.

13. View history

gent log
gent log --oneline
gent show --no-patch

14. Push to the remote API

gent push

Expected result:

Pushed 1 commit(s) to origin/main

Run it again to confirm nothing else needs syncing:

gent push

Expected result:

Everything up-to-date

15. Clone from the remote API

Go outside your current project:

cd ..
gent clone /api/repos/2/my-project my-project-clone
cd my-project-clone

Check the cloned files:

cat README.md
gent status
gent log --oneline

16. Make another change in the original repo

cd ../my-project
echo "Second line" >> README.md
gent add README.md
gent commit -m "Update README"
gent push

17. Pull the change into the clone

cd ../my-project-clone
gent pull
cat README.md
gent status

Expected result: the clone fast-forwards, README.md includes the new line, and status shows no staged changes.

18. Create and sync a branch

From a repository with at least one commit and an origin remote:

gent branch feature-login
gent branch

Switch to the branch:

gent checkout feature-login

Make a change:

echo "feature work" > feature.txt
gent add feature.txt
gent commit -m "Add feature work"
gent push origin feature-login

Switch back to main:

gent checkout main

19. Merge a branch

gent merge feature-login
gent push

If there are conflicts, resolve them interactively (recommended):

gent resolve        # walk each conflict; it can finalize the merge commit for you
gent push

Or resolve the markers by hand, then:

gent add .
gent commit -m "Resolve merge"
gent push

20. Create and sync a tag

Create a lightweight tag:

gent tag v1.0.0

Create an annotated tag:

gent tag v1.0.1 -m "Release v1.0.1"

List tags:

gent tag

Delete a tag:

gent tag -d v1.0.0

21. Use stash when needed

Save local work:

gent stash

List stashes:

gent stash list

Apply latest stash:

gent stash pop

22. Log out

gent logout

Confirm:

gent whoami

Expected result: not logged in.

One-Command Remote Repo Setup

You can initialize a local repo and create the remote repo in one command:

mkdir another-project
cd another-project
gent init --remote another-project
gent remote -v

This creates the remote repository on https://gent-api.onrender.com and configures origin automatically.

Command Reference

Authentication

gent register
gent register -e [email protected] -p StrongPass123! --password-confirm StrongPass123!
gent login
gent login -e [email protected] -p StrongPass123!
gent whoami
gent logout

Repository Setup

gent init
gent init --remote my-repo
gent clone /api/repos/<owner_id>/<repo_name> [directory]

Staging and Working Tree

gent status
gent status -s
gent add <files...>
gent add .
gent rm <files...>
gent rm <files...> --cached
gent reset [files...]
gent reset --soft <commit_hash>
gent reset --hard <commit_hash>
gent diff
gent diff --staged
gent diff --stat

History

gent commit -m "Message"
gent log
gent log --oneline
gent log -n 5
gent show
gent show <commit_hash>
gent show --no-patch

Branching and Merging

gent branch
gent branch <name>
gent branch -d <name>
gent checkout <branch>
gent checkout -b <branch>
gent merge <branch>
gent merge <branch> -m "Merge message"
gent resolve                      # interactively resolve merge conflicts

Safety Net (undo / redo)

gent undo                         # reverse the last commit/merge/reset/checkout
gent undo --list                  # show the operation history
gent redo                         # re-apply the last undone operation

Undo never deletes your working files; for content-discarding operations (reset --hard, fast-forward merge, pull) it restores them from the object store.

Insight

gent summary                      # repository health & statistics dashboard
gent summary --ai                 # + a short AI-written assessment (needs a key)
gent log --graph                  # ASCII commit graph with branches and merges
gent explain                      # explain the latest commit in plain language
gent explain <commit>             # explain a specific commit
gent explain --staged             # explain currently staged changes

Optional AI features

AI is off by default and every feature has a non-AI fallback. Enable it with:

export ANTHROPIC_API_KEY=sk-ant-...
export GENT_AI_MODEL=claude-haiku-4-5   # optional; default is claude-opus-4-8

gent commit --ai                  # suggest a commit message from the staged diff
gent explain                      # narrate a diff instead of just printing it
gent resolve                      # adds an "Ask AI" choice per conflict hunk

Tags

gent tag
gent tag <name>
gent tag <name> -m "Message"
gent tag -d <name>

Remotes and Sync

gent repos
gent repos --create <name>
gent repos --create <name> --description "Description"
gent repos --create <name> --private
gent remote
gent remote -v
gent remote add origin /api/repos/<owner_id>/<repo_name>
gent remote set-url origin /api/repos/<owner_id>/<repo_name>
gent remote remove origin
gent push
gent push origin main
gent pull
gent pull origin main

Remote URL Rules

The global API base is fixed:

https://gent-api.onrender.com

Remote repository paths should be stored like this:

/api/repos/<owner_id>/<repo_name>

Example:

gent remote add origin /api/repos/2/my-project

Do not use:

http://localhost:8000
http://127.0.0.1:8000

Files Created by Gent

Inside each repo:

.gent/
├── config.json
├── commits.json
├── staging.json
├── journal.json   # operation journal for undo/redo (created on first op)
├── HEAD
├── objects/
└── refs/

.gentignore

Global auth:

~/.gent/auth.json

Ignore Rules

Gent creates a .gentignore file by default:

node_modules/
.DS_Store
*.log
.env
.gent/

Add project-specific ignored files there.

Test the Full Remote Flow

This repository includes a remote-only E2E test. It uses only:

https://gent-api.onrender.com

Run syntax checks:

npm test

Run the full remote scenario:

npm run test:remote:e2e

The test covers:

• API health check
• Register, login, whoami, logout
• Create and list remote repositories
• Init, remote add, status, add, diff, commit
• Push and up-to-date push
• Branch sync
• Tag sync
• Clone from remote
• Second commit and push
• Pull into clone and verify working tree content
• init --remote
• Unauthenticated guard
• Version flag

Troubleshooting

Command not found

Install or link the CLI:

npm install -g gent-cli

or:

cd apps/Cli
npm link

Not authenticated

Log in again:

gent login

Not a Gent repository

Run commands inside a folder initialized with:

gent init

Remote not found

Add an origin remote:

gent remote add origin /api/repos/<owner_id>/<repo_name>

Push says everything up-to-date

That means the local branch has no new commits compared to the last pushed remote ref.

Render cold start

The deployed API may take several seconds to respond after inactivity. Retry the command if the first request times out.

Version

Show the CLI version:

gent -V
gent --version

License

ISC