Repository navigation
Releases
lg v0.1.1 — first public release
First public release of lg, a command-line client for Labguru modelled on GitHub's gh: lg <object> <verb>, readable tables, JSON for scripts, and authentication handled for you. It works with any instance (my.labguru.com or a hosted one such as cle.inserm.fr), any account and any workspace, and it can publish your own notebook, written as Markdown files, to a Labguru project.
En français : l'interface passe en français quand LANG ou LC_ALL commence par fr.
v0.1.0 was tagged but never released (the build was cancelled), so these notes cover everything.
Install
cargo install labguru-cliOr download a binary below, unpack it and put lg on your PATH. Each archive also holds the man page (lg.1), shell completions (bash, zsh, fish, PowerShell), the README and the licence.
| System | Archive |
|---|---|
| macOS, Apple silicon | lg-v0.1.1-aarch64-apple-darwin.tar.gz |
| macOS, Intel | lg-v0.1.1-x86_64-apple-darwin.tar.gz |
| Linux x86_64 (static, musl) | lg-v0.1.1-x86_64-unknown-linux-musl.tar.gz |
| Linux ARM64 (static, musl) | lg-v0.1.1-aarch64-unknown-linux-musl.tar.gz |
| Windows x86_64 | lg-v0.1.1-x86_64-pc-windows-msvc.zip |
Then follow the README, which is a 15-minute tutorial.
What's in it
Authentication
lg auth login | status | logout | switch: log in with e-mail and password, or with a token on standard input (--with-token, needed with SSO).- The token is kept in the system keychain (macOS Keychain, Windows Credential Manager, Secret Service on Linux), or else in a file readable only by you (mode 600).
- Several hosts and several accounts or workspaces per host, as with gh.
LABGURU_TOKENandLABGURU_HOSTfor CI and servers.- What your instance's API supports is read from its
/api-docs; a missing feature gives a clear message instead of an HTTP error.
Objects
project,folder,experiment,section,note,paperandattachment, each withlist,view,create,editanddelete.experiment movemoves an experiment to another folder.experiment editwith only one date keeps the duration right.paper addimports papers from a BibTeX file (authors, editors,date, DOI and URL kept).attachment upload | download, andtag list | create | delete.--webandlg browseopen any object in the browser.experiment flagandexperiment signonly explain how to do it in the web page: lg never signs anything.
Output and scripting
- Output as in gh: a table on a terminal, tab-separated values when piped, JSON with
--json field,..., filtered with--jq(csv and tsv formats included), shaped with--template. NO_COLORis honoured.- Exit codes: 0 success, 1 error (or differences found by
notebook check), 2 wrong usage, 4 not logged in or token refused. lg apicalls any endpoint with your token added. It supports-X,-ffields,--inputfor a JSON body (POST by default),--paginate,--jq, and API v2 paths.lg aliasfor shortcuts, andlg configfor settings (browser, prompts).lg completion <shell>andlg man.LG_DEBUG=1prints each request (method and path only, never the token).
Notebook: publish Markdown to Labguru
lg notebook initcreates a notebook skeleton with a worked example;lg notebook newadds a dated entry.lg notebook pushis a dry run that lists what would be created, changed, moved or removed.--applywrites the changes.lg notebook checkreads Labguru back and reports any difference.- Each notebook folder becomes a Labguru folder, and each entry becomes an experiment with Description, Procedure and Results sections. Images are uploaded, notes and attachments are added, and papers come from
references.bib. - Entries are filed by status (planned, in progress, done), worked out from the text or set with a
status:header. Dates come from the header or from the dates cited in the entry, and never fall after today. - Idempotent and safe:
- objects are matched by
external_uuid(lg:<project>/<folder>/<file>), so running push again sends only what changed, and "Labguru is up to date" when nothing did; - nothing is duplicated, and no experiment is ever deleted;
- a text block holding your team's inline comments is never overwritten (lg warns instead).
- objects are matched by
- Examples in English (
examples/notebook) and French (examples/cahier).
Labguru API quirks handled for you
Tested on a real hosted instance (cle.inserm.fr) and on my.labguru.com:
- Token and requests:
- the token goes in the query for GET (and for every API v2 request), and in the JSON body otherwise;
- PUTs can answer with an empty body;
- reads are retried on 429 and 5xx (after 5 s, 30 s, then 120 s), and writes are never sent twice.
- Folders:
- a nested folder's
ancestrygets cut at creation, so lg sets it again with a PUT; - folder status is stored as
completed,currentandcompleation_date.
- a nested folder's
- Text and HTML:
- Labguru rewrites HTML (
<br />,", checkboxes), and lg ignores these rewrites when comparing, so a push does not report false changes; - Markdown task lists are sent as ☑ / ☐, since Labguru removes checkboxes.
- Labguru rewrites HTML (
- Limits, reported clearly:
- a project description can only be set at creation;
- deleting a project needs API v2.
Changes since the v0.1.0 tag
- The README is now a step-by-step tutorial.
lg notebook newnames filesYYYY-MM-DD-<title>.mdand no longer writes a status header.cargo install labguru-clinow works.
Known limits
- The Successful / Failed flag and signatures can only be set in the web page.
- A folder's start date can only be set when the folder is created.
- On macOS, the keychain asks again after each update of
lg: click Always Allow.
Full history: https://github.com/IPNP-BIPN/labguru-cli/commits/v0.1.1