📚 Help › Isurus CLI (isu)

Isurus CLI (isu)

isu is the official command-line client for Isurus. It talks to the forge REST API so you can manage organizations, repositories, issues, pull requests, CI pipelines, and releases from a terminal — similar in spirit to GitHub’s gh or GitLab’s glab, but built for Isurus and multi-VCS (Mercurial, Git, and Fossil).

What isu is not: it does not replace hg, git, or fossil for day-to-day version control. Clone, commit, push, pull, and LFS still use your VCS client. Use isu for forge product operations (issues, PRs, CI status, releases, and helpers such as isu repo clone / isu browse).

The CLI is distributed independently of your tenant image: you install one binary and point it at any Isurus host (this instance or another) with a personal API token.

Install

On Linux, macOS, FreeBSD, or illumos (and Windows via WSL):

curl -fsSL https://isu.isurus.dev/install.sh | sh

By default this installs to ~/.isurus/bin/isu and may append that directory to your shell PATH (for example in ~/.zshrc or ~/.bashrc). Open a new shell or source your rc file, then check:

isu version

Pin a release:

curl -fsSL https://isu.isurus.dev/install.sh | ISU_VERSION=0.1.0 sh
Environment variable Purpose
ISU_VERSION Install a specific version (e.g. 0.1.0) instead of latest
ISU_INSTALL_DIR Install directory (default ~/.isurus/bin)
ISU_BASE_URL Override the download CDN base (mirrors / air-gapped)
ISU_SKIP_PATH If set, do not modify shell rc files

Source and release history live in the public isurus/isu repository on Leafscale’s forge. Reinstall with the same curl | sh line to upgrade when a new release is published.

Authenticate

isu uses a personal API token, not your web password or SSO session. Tokens are created in the web UI and stored locally under ~/.isurus/config/ (host entries are mode 0600).

1. Create a token

  1. Open your user menu (top-right) → Settings → Tokens.
  2. Click New token.
  3. Choose scopes for what you need (see below).
  4. Create the token and copy it immediately — it is shown only once.

Suggested scopes

Work Scopes
Read-only exploration repo:read, issues:read, ci:read, releases:read
Issues and PRs add issues:write (and repo:read / write as needed for PRs)
CI cancel / rerun ci:write
Create releases / upload assets releases:write

If your organization uses SAML or OIDC, the same token model applies for both VCS over HTTP and isu. See CLI Access with SSO.

2. Log in with isu

Interactive (prompts for host URL and token):

isu auth login

Non-interactive:

printf '%s' "$ISURUS_TOKEN" | isu auth login \
  --host-url https://your-instance.example.com \
  --name myforge \
  --token-from-stdin

Useful checks:

isu auth status    # active host, user, API reachability
isu auth list      # all saved hosts
isu auth use myforge

Do not put tokens on the process command line in scripts if you can avoid it (ps and shell history). Prefer --token-from-stdin or --token-file.

Multiple forges

You can save several hosts and switch with isu auth use <name> or pass --host <name> on any command. One install of isu can talk to many tenants.

Command overview

Command Purpose
isu auth Login, logout, status, multi-host
isu org List / view organizations and members
isu repo List, view, create, clone repositories
isu issue List, view, create, comment, close, reopen
isu pr List, view, create, comment, checkout, merge
isu ci List / view pipelines; logs; cancel and rerun
isu release List, view, create releases
isu browse Open the forge (or an issue/PR) in a browser
isu config CLI preferences (ui.output, etc.)
isu completion Shell completion scripts
isu version Print CLI version
isu upgrade Self-update from the public CDN

Every command supports -h / --help. Global flags include --host, -o json|human, -v (verbose HTTP with tokens redacted), and --no-color.

Working from a repository checkout

When your current directory is a clone of a repo on the active Isurus host, most commands infer org/repo from the remote. You can always pass it explicitly:

isu issue list myorg/myrepo
isu issue list              # from a clone of myorg/myrepo

isu detects Mercurial, Git, and Fossil checkouts.

Common workflows

Organizations and repositories

isu org list
isu org view myorg
isu repo list                 # repos across orgs you belong to
isu repo list myorg
isu repo view myorg/myrepo
isu repo clone myorg/myrepo   # uses hg, git, or fossil based on forge metadata

Issues

isu issue list myorg/myrepo
isu issue list myorg/myrepo --state open
isu issue view myorg/myrepo 42
isu issue create myorg/myrepo -t "Title" -b "Body"
isu issue comment myorg/myrepo 42 -b "Update from CLI"
isu issue close myorg/myrepo 42
isu issue reopen myorg/myrepo 42

New issues start in state new. Default list state is all so newly filed issues appear immediately. See the Issue Tracker Guide for the full state model.

Pull requests

# After pushing a bookmark (hg) or branch (git/fossil):
isu pr create -t "Fix login redirect" -b "Details…"
isu pr list
isu pr view 12
isu pr comment 12 -b "LGTM"
isu pr checkout 12    # update local checkout to the PR source ref
isu pr merge 12

--head / --source and --base / --target control source and target refs; defaults come from the current checkout and repo default when possible. See Pull Requests for the web review workflow.

CI pipelines

isu ci list --limit 10
isu ci view 7
isu ci logs 7              # all steps with available logs (needs ci:read)
isu ci logs 7 --step test  # one step by name or number
isu ci cancel 7            # needs ci:write
isu ci rerun 7             # needs ci:write

isu ci logs fetches a snapshot of step output over the API. Live streaming is still in the web UI — isu ci view prints a Web: URL. Authoring pipelines is covered in the CI/CD Guide.

Releases

isu release list myorg/myrepo
isu release view myorg/myrepo v1.2.3
isu release create myorg/myrepo --tag v1.2.3 -t "1.2.3"

Creating releases and attaching assets typically requires releases:write. Large multi-platform asset uploads are often done from CI (see the CI/CD release block); isu release is useful for inspection and simple creates.

Open in browser

isu browse
isu browse --issue 42
isu browse --pr 12

Scripting and output

Human-readable tables are the default. For automation:

isu issue list myorg/myrepo -o json
isu ci view 7 -o json

You can set the default with:

isu config set ui.output json
isu config list

Local configuration

Path Role
~/.isurus/bin/isu Default install location of the binary
~/.isurus/config/hosts.toml Saved forge hosts and tokens (permissions restricted)
~/.isurus/config/config.toml CLI preferences

Shell completion

# bash
isu completion bash > /etc/bash_completion.d/isu   # or source from ~/.bashrc

# zsh
isu completion zsh > "${fpath[1]}/_isu"

# fish
isu completion fish > ~/.config/fish/completions/isu.fish

See isu completion --help for your shell.

Upgrade

isu upgrade --check          # current vs latest on the CDN
isu upgrade                  # install latest if newer
isu upgrade --version 0.1.1  # pin a version
isu upgrade --force          # reinstall even if already current

Downloads from https://isu.isurus.dev by default (override with --base-url or ISU_BASE_URL), verifies SHA-256, and replaces the running binary in place. Requires write access to the install path (e.g. ~/.isurus/bin).

Limitations (current)

  • isu token management subcommands are not implemented yet — create and revoke tokens in Settings → Tokens in the web UI.
  • isu ci logs --follow (live stream) is not available; use the web pipeline page for live logs.
  • Native Windows is not supported; use WSL and install inside Linux.
×