Skip to content
Simply SF logoSimply SF logoSimply CLI

Get Started

Requirements

Section titled “Requirements”
  • Node.js 22 or later
  • A GitLab account on gitlab.com or a self-managed instance, and an access token

Install

Section titled “Install”
Terminal window
npm install -g @simplysf/simply-cli

Verify it worked

Section titled “Verify it worked”
Terminal window
simply gitlab --help

Get a token

Section titled “Get a token”

Create a personal access token under Preferences › Access tokens in GitLab, or a project or group access token from that project’s or group’s settings. Two scopes matter:

ScopeWhat it allows
read_apiEverything on this site that reads. Nothing that writes.
apiReads and writes.

Start with read_api. It is not just a smaller permission — it is the only thing that makes a write structurally impossible, which matters as soon as a script or an agent is running these commands. See Write safety.

Connect to your instance

Section titled “Connect to your instance”

Every command reads its connection settings from environment variables, from flags, or from a .env file passed with -e/--env-file:

GITLAB_TOKEN=glpat-...
GITLAB_URL=https://gitlab.example.com   # omit entirely for gitlab.com

GITLAB_URL defaults to https://gitlab.com, so a gitlab.com user needs only the token. See Credentials for precedence between flags, environment, and file, and for trusting an internal certificate authority.

First commands

Section titled “First commands”

Find a project you can reach, then look at its open merge requests:

Terminal window
simply gitlab project list --membership
simply gitlab mr list --project group/project

Add --json to either to get the raw API payload instead of the formatted table.

Naming a project

Section titled “Naming a project”

Every project-scoped command takes -p/--project, which accepts a numeric id or the full path. Both of these are the same project:

Terminal window
simply gitlab mr list --project 1234
simply gitlab mr list --project group/subgroup/project

The path is URL-encoded for you — do not encode it yourself. If you work in one project most of the time, set GITLAB_PROJECT and drop the flag.

Where to go next

Section titled “Where to go next”
  • The Command Reference lists every command by topic, with its flags and examples.
  • Credentials covers tokens, precedence, and certificates.
  • Write safety explains --dry-run, GITLAB_READ_ONLY, and why a read_api token is the only one of those that actually binds.
  • Scripts and agents covers the --json contract and exit codes.
  • MCP server gives an AI agent the same capabilities as tools, read-only by default.
  • Want to contribute? See CONTRIBUTING.md in the repo.