Documentation

squrlnest-cli

A git-like command-line client for pushing, pulling, cloning, and browsing repositories hosted on a Forage Customer Portal server — what we call a Squrl Nest.

Overview

Every Forage Customer Portal doubles as a lightweight, self-hosted repo host — repos, branches, commits, issues, and projects, without leaving your own infrastructure. squrlnest-cli is how you talk to it from a terminal or from a script, the same way git talks to GitHub.

The npm package is named squrlnest-cli, but the command it installs is squrlnest. After installing, run squrlnest, not squrlnest-cli.

It's intentionally simpler than git: fast-forward-only pushes and pulls (no three-way merges from the CLI — merging branches together happens from the Customer Portal's Compare & Merge page), plus a set of gh issue-style commands for reading and writing issues, which makes it a natural tool for an AI coding agent to drive directly.

Install

npm install -g squrlnest-cli

Requires Node.js 18+.

Getting an API token

The CLI authenticates with an API token, not your portal password. Get one from your Forage Customer Portal's Profile page (My Profile → API token).

# One-time: save your server URL and token so you don't have to pass them to every command
squrlnest login https://your-forage-portal.example.com YOUR_API_TOKEN

Quickstart

# Create a brand-new repo on the server and connect this folder to it
squrlnest init my-project
echo "hello" > README.md
squrlnest commit -m "Initial commit"
squrlnest push

# ...or clone an existing repo into a new folder
squrlnest clone my-project
cd my-project

Everyday workflow

# See what's changed
squrlnest status
squrlnest diff

# Commit and share your changes
squrlnest commit -m "Fix the thing"
squrlnest push

# Get other people's changes
squrlnest pull

Working with branches

# List local branches (* marks the current one)
squrlnest branch

# See what branches exist on the server, including ones you haven't fetched yet
squrlnest branch -r

# Create a new branch (forked from your current branch) and switch to it
squrlnest branch feature-x

# Switch branches — fetches the branch from the server automatically if you
# don't have it locally yet (e.g. one created from the Customer Portal)
squrlnest checkout main

# Push/pull a specific branch instead of your currently-checked-out one
squrlnest push --branch feature-x
squrlnest pull --branch feature-x

This tool is fast-forward-only. If a push is rejected because the remote has moved on, run squrlnest pull first. If that refuses because both sides have commits the other hasn't seen, that's a real divergence — note your local commit ids with squrlnest log, then use squrlnest pull --force to discard local commits and take the remote's version (recoverable via squrlnest rollback <commitId> until you commit/push again).

Ignoring files (`.squrlnestignore`)

Works like .gitignore: files and folders that match a pattern in .squrlnestignore (at the root of the connected folder) are never treated as changed and never get committed or pushed.

squrlnest ignore add "*.log" build/ .env
squrlnest ignore list
squrlnest ignore remove "*.log"

Patterns support */? wildcards, ** for any depth, a trailing / to match directories only, ! to negate an earlier pattern, and # for comments. A pattern with no / matches at any depth; a pattern containing a / is anchored to the folder root.

Working with issues

gh issue-style commands for viewing and editing issues — useful for scripting, or for an AI agent working from a connected/cloned folder to read an issue's context and write its findings back onto it, not just push code.

squrlnest issue list
squrlnest issue list --status open

squrlnest issue view 42
squrlnest issue view 42 --comments

squrlnest issue create --title "Add a LICENSE file" --body "..." --label sfactory:ready-for-spec

squrlnest issue edit 42 --body "Updated description..." --status closed

squrlnest issue comment 42 "Investigated - root cause is..."

squrlnest issue label add 42 bug needs-triage
squrlnest issue label remove 42 needs-triage

Unlike the git-like commands above, issue commands don't need a connected folder — pass --repo <name> (plus --server/--token, or a prior squrlnest login) to use them from anywhere. Run from inside a connected/cloned folder, --repo is optional and defaults to that folder's own repo.

Updates

squrlnest checks the Squrl Update Service for a newer version roughly once a day as a courtesy (after whatever command you ran finishes, so it never slows a command down) and prints a note if one's available.

squrlnest update                  # check now
squrlnest update --install        # check now and install if available
squrlnest update --channel beta   # switch update channel (stable|beta)
squrlnest update --auto true      # install updates automatically once found

An install stages and swaps in the new version once the current command exits — no restart needed, just run squrlnest again afterward.

Command reference

Command	Description
`squrlnest login <serverUrl> <token>`	Save the default server URL and API token globally.
`squrlnest init <repoName>`	Create a new repo on the server and connect the current folder to it.
`squrlnest clone <repoName> [dir]`	Clone a repo's current files into a new folder (defaults to `./<repoName>`).
`squrlnest connect <repoName>`	Connect the current folder to an existing repo without downloading its files.
`squrlnest status`	Show the connected repo, tracked branch, local/remote HEAD, and uncommitted changes.
`squrlnest diff [file]`	Show uncommitted changes in the working directory.
`squrlnest commit -m "<message>"`	Commit the working directory as a new local snapshot on the current branch.
`squrlnest push [--branch <branch>]`	Push local commits to the remote (defaults to the current branch).
`squrlnest pull [--branch <branch>] [--force]`	Pull new commits from the remote. `--force` discards local unpushed commits on divergence.
`squrlnest log [--branch <branch>]`	Show local commit history.
`squrlnest rollback <commitId>`	Restore the working directory to match a previous commit.
`squrlnest branch [name] [-r]`	List local branches, or create/switch to a new one. `-r` lists remote branches.
`squrlnest checkout <name>`	Switch to a branch, auto-fetching it from the remote first if needed.
`squrlnest update [--install] [--channel <name>] [--auto <true\|false>]`	Check for CLI updates, optionally install one, and/or change update settings.
`squrlnest ignore add/remove/list`	Manage `.squrlnestignore` patterns.
`squrlnest issue list [--status <status>]`	List issues, optionally filtered by status.
`squrlnest issue view <number> [--comments]`	Show an issue's details; `--comments` includes its comment thread.
`squrlnest issue create --title <title> [...]`	Create a new issue (`--type`: bug/feature/task/enhancement/question).
`squrlnest issue edit <number> [...]`	Edit an issue's title, body, and/or status.
`squrlnest issue comment <number> <body>`	Add a comment to an issue.
`squrlnest issue label add/remove <number> <label...>`	Manage labels on an issue.

Every command also accepts --help, e.g. squrlnest commit --help.

Config files

Path	Contains
`~/.squrlnest/credentials.json`	The default server URL/token saved by `squrlnest login`, plus update settings.
`.squrlnest/` (per connected folder)	That folder's server connection, tracked branch, local commit history, and blob store. Safe to delete to disconnect (you'll lose unpushed local commits).
`.squrlnestignore` (per connected folder, optional)	Ignore patterns — see Ignoring files above.

What's next

Actively in progress: automatic knowledge-graph generation the first time squrlnest-cli (or Forage) opens a repo it hasn't seen before, and a Squrl Nest MCP server that exposes clone/commit/push/pull directly to AI agents alongside the CLI.