gi-ingest CLI Guide

Offload robotics recordings from TF cards and deliver them to GILabs Data Platform.

Reads ego rig cards, copies each session to a local disk and verifies the copy, delivers the lot to GILabs as one sealed batch, and wipes the cards only once the server confirms it holds the data. Built for the way an offload actually goes: someone swapping cards at a reader for half an hour, a link pushing bytes overnight with nobody watching, and a wipe the next morning.

Installation

macOS and Linux. Windows is not supported: cards are looked for under /Volumes and /media, so a Windows install finds nothing.

Prerequisite — uv, once per machine. It fetches its own Python, so nothing else needs installing first.

curl -LsSf https://astral.sh/uv/install.sh | sh

Reopen your terminal afterwards so uv is on your PATH, then install the CLI into an isolated environment of its own:

uv tool install gi-ingest
gi-ingest --version

Authentication

Get a token from the vendor portal at vendor.gilabs.xyz → Upload tokens. It is shown once and stored only as a hash, so copy it when it appears — the portal prints the whole command below with your token already in it.

gi-ingest login --api-key gik_...
gi-ingest doctor

doctor checks the four things an overnight run depends on: your version, your token, that a delivery destination has been granted, and that the staging disk has room. Run it before a session rather than discovering a problem at 2am.

Configuration

Everything is stored per machine in ~/.config/gi-ingest/config.json, which also holds your token and is written owner-readable only.

gi-ingest config show                                   # settings and where they live
gi-ingest config set staging-dir /Volumes/BigDisk/gilabs

Any of them can be overridden for a single run without changing what is stored:

gi-ingest stage --staging /Volumes/OtherDisk/gilabs
gi-ingest stage --project <id>
gi-ingest upload --ledger /Volumes/OtherDisk/other.db

--ledger is how you keep two independent offload runs on one machine from sharing state — each needs its own, or they will see each other's queues.

The ledger is worth knowing about even though you rarely touch it. It is what makes an interrupted upload resumable and lets reclaim know which cards are safe to wipe, so it is the one file where losing it costs you a re-stage rather than nothing. It survives upgrades, including the rename from gilabs-ingest.

Upload a batch

One loop per round of cards: copy them, push them overnight, wipe them the next morning. Three commands rather than one because they run on two different timescales, and fusing them turns a 30-minute attended task into an all-night one.

# 1. Drain every card. Swap cards as each finishes; nothing is wiped yet.
gi-ingest stage
gi-ingest stage --watch                 # or let it auto-copy on insert

# 2. Leave this running. One delivery, resumable, safe to nohup.
gi-ingest upload --max-bandwidth 50M

# 3. Next morning, with the cards back in the reader.
gi-ingest reclaim

1 — stage copies each session to the staging disk, checksums it on the way back out, and tells you which project the round is bound for before it starts. The card is left completely intact, so it can be pulled the moment a copy finishes.

2 — upload opens a batch and receives AWS credentials scoped to that batch's folder alone; they cannot read or write anything else, including your own other deliveries. Files go straight to S3, and the credentials are re-minted as they expire, so a multi-hour run and a laptop that sleeps both just work. It then seals the batch with a manifest listing every episode, part, size and SHA-256, and GILabs verifies every declared file is present at its declared size before ingesting anything — a half-finished upload can never be processed as if it were complete.

3 — reclaim wipes only what the server has confirmed, checking each card's own metadata against its records first. It clears the staging copy at the same time, which is the one that actually fills a disk.

Commands

gi-ingest --version       # what you are running
gi-ingest whoami          # vendor, scopes, and where you may deliver
gi-ingest destinations    # the org/project list, with ids for --project
gi-ingest doctor          # version, token, destination, disk
gi-ingest queue           # what is staged / in flight / delivered
gi-ingest status          # deliveries and their QC verdicts
gi-ingest status --batch btch_...
gi-ingest retry           # re-queue anything that failed

FAQ

The upload was interrupted — do I start again?

No. Re-run gi-ingest upload. It re-uses the same open delivery and skips files already sent, so a restart costs a listing rather than the bytes. That covers a kill, a crash, a dropped connection or a closed lid.

Why is wiping the cards a separate step?

upload finishes hours after the cards were pulled, so it cannot wipe them — they are back in the rig by then.

It also means the card keeps a second copy until reclaim runs, which is deliberate: between stage and confirmation the staging disk would otherwise be the sole home of a whole collection round.

Where do the cards get copied to?

~/gilabs-staging by default, which is rarely where a multi-terabyte round fits. Point it at the right disk once — see Configuration.

Which project does a delivery go to?

Every delivery is filed against one project, and destinations are granted by GILabs — you cannot add one yourself. If the portal's Destinations tab is empty, ask your GILabs contact.

With one granted destination there is nothing to choose and no flag to pass. With several, you have to say which, before staging rather than at upload:

gi-ingest destinations --select     # pick from a list; saved for this machine
gi-ingest destinations              # just show them
gi-ingest stage --project <id>      # or choose for a single run

You will also be asked directly the first time stage needs to know and the answer is not obvious. A project id is a uuid, and retyping one off a portal page is how a delivery ends up under the wrong project.

stage refuses to copy anything until this is settled, and both stage and upload print the destination before they start. That is deliberate rather than fussy: a delivery goes to one project, so cards staged for two of them in the same session would be filed together and only one of them correctly — and nothing about the upload would look wrong while it happened.

For the same reason upload refuses a queue holding episodes staged for different projects. Upload one destination's worth at a time.

What happens if a card was already delivered by someone else?

stage asks GILabs which episodes it already has before copying, so a card a colleague already delivered costs one request instead of its bytes. Offline, it stages anyway and says so; the duplicate is caught server-side at seal.

Upgrading

uv tool install --upgrade gi-ingest

Worth doing when doctor says so. Older versions are refused for upload and reclaim, because some of them lost data without reporting it — a card wiped against another card's confirmation, and an interrupted upload that could never be sealed.

Getting help

gi-ingest doctor first: it answers most questions, and its output is the useful thing to send on. Then your GILabs contact, with the version it printed.