Command-line tool

giga does everything the web app does from a terminal: projects, branches, check out and check in, versions, release requests, and exporting releases. Use it to script GigaCAD, to work on macOS or Linux, or in CI.

Install

giga needs Node.js 22 or later. Install it from npm:

npm install -g @gigacad/cli
giga --version

giga login

This opens app.gigacad.site/device in your browser with a code. Check that the code matches your terminal, then approve it. giga saves a device token for this computer in ~/.config/giga on macOS and Linux, or %APPDATA%\giga on Windows. Use giga login --no-browser to print the link instead of opening it.

giga whoami shows who you’re signed in as. giga logout revokes this computer’s token. You can also sign devices out under Account in the web app.

Workspaces

giga clone downloads one branch into a new folder, called a workspace. Commands you run inside a workspace act on its project and branch, so most of them need no arguments. Outside a workspace, pass --project owner/project. The workspace keeps its state in a .giga folder; don’t edit or copy it.

A typical session

giga branch create gripper-v2 --project alex/robot-arm
giga clone alex/robot-arm --branch gripper-v2 gripper
cd gripper
giga checkout      # take the write lock, get the latest files
# ...edit files in SolidWorks...
giga status        # see what changed
giga commit -m "Stiffer jaw" --label "rev B"
giga checkin       # give the lock back

Only the person who has a branch checked out can commit to it. If someone else holds the lock, giga checkout says who. giga checkin refuses while you have uncommitted changes; --force checks in anyway and leaves your local files alone.

giga pull never overwrites local changes. If a newer commit touches a file you changed, it stops and lists the files without changing anything.

To rename or move a file, use giga mv old new rather than your file manager. That keeps the file’s identity, so its history continues and release requests treat it as the same part.

Release from the command line

giga rr open --title "Gripper v2"
giga rr diff                     # what differs from main
giga rr picks --file picks.json  # optional
giga rr candidate
giga rr approve
giga rr release --notes "Stiffer jaw, new fingertip"

By default each changed file takes the branch’s copy. To choose differently, write a picks file. Files are named by path. keep_main leaves main’s copy, and a replacement ships a new part in place of an old one, keeping the old part’s identity:

{
  "actions": {
    "parts/jaw.SLDPRT": "take_branch",
    "parts/base.SLDPRT": "keep_main"
  },
  "replacements": [
    {
      "branchPath": "parts/finger_v2.SLDPRT",
      "mainPath": "parts/finger.SLDPRT"
    }
  ]
}

Changing picks discards the candidate, so run giga rr candidate again. giga rr show lists what still blocks the release, like missing approvals.

Commands

Account

giga login: Sign in through your browser and save a device token.
giga whoami: Show who you’re signed in as.
giga logout: Revoke this computer’s token and forget it.

Projects and branches

giga project list: Projects you’re a member of.
giga project create <slug>: Create a project you own. Private unless --public; set --name and --description.
giga project show [project]: A project, its branches, and its latest release.
giga branch list: Branches of a project.
giga branch create <name>: Start a branch from the latest release, or from --from-release N.

Workspace

giga clone <project> [folder]: Download a branch into a new folder. Choose it with --branch.
giga checkout: Take the branch’s write lock for this computer, then pull its latest files.
giga pull: Download the branch’s latest commit without losing local changes.
giga status: Local changes, plus who has the branch checked out and whether you’re up to date.
giga mv <from> <to>: Move or rename a file or folder, keeping each file’s identity.
giga commit -m <message>: Upload every changed file as a version. Name it with --label.
giga checkin: Give up the write lock. --force skips the uncommitted-changes check.
giga export <file> <export>: Attach a STEP or STL you exported from SolidWorks to a committed part or assembly. It becomes the file’s preview, and people can download it.

Release requests

Inside a workspace these act on the branch’s open request. Elsewhere, pass the request number, like giga rr show 3.

giga rr open: Open a release request. Set --title and --body. The branch freezes until it’s released or closed.
giga rr list: Active release requests. --all includes released and closed ones.
giga rr show: Status, candidate, approvals, and what blocks the release.
giga rr diff: Every file changed on the branch or on main since the branch started.
giga rr picks --file <path>: Replace the picks with a JSON file, or - for standard input.
giga rr candidate: Build the release candidate from the current picks.
giga rr rebuild-report --file <path>: Attach the result of rebuilding the candidate in your CAD program.
giga rr approve: Approve the current candidate.
giga rr unapprove: Withdraw your approval.
giga rr release: Publish the approved candidate as the next release. Add --notes.
giga rr close: Close without releasing. The branch unfreezes.

Releases

giga release list: Releases, newest first.
giga release show <number>: A release and its files.
giga release export <number> [folder]: Download a release into a new folder, checking every file against its recorded hash.

Scripting

Add --json to any command for machine-readable output; errors then go to standard error as JSON. These environment variables change where giga connects and signs in:

GIGA_TOKEN: A device token to use instead of the saved sign-in. It’s never saved. Use it in CI.
GIGA_API_URL: A different API, for example a local one. Same as --api-url.
GIGA_CONFIG_DIR: Where sign-ins are saved.