Skip to content

Releases

lg v0.1.1 — first public release

Choose a tag to compare

@github-actions github-actions released this 04 Nov 14:21

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-cli

Or 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_TOKEN and LABGURU_HOST for 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, paper and attachment, each with list, view, create, edit and delete.
  • experiment move moves an experiment to another folder. experiment edit with only one date keeps the duration right.
  • paper add imports papers from a BibTeX file (authors, editors, date, DOI and URL kept).
  • attachment upload | download, and tag list | create | delete.
  • --web and lg browse open any object in the browser.
  • experiment flag and experiment sign only 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_COLOR is honoured.
  • Exit codes: 0 success, 1 error (or differences found by notebook check), 2 wrong usage, 4 not logged in or token refused.
  • lg api calls any endpoint with your token added. It supports -X, -f fields, --input for a JSON body (POST by default), --paginate, --jq, and API v2 paths.
  • lg alias for shortcuts, and lg config for settings (browser, prompts).
  • lg completion <shell> and lg man.
  • LG_DEBUG=1 prints each request (method and path only, never the token).

Notebook: publish Markdown to Labguru

  • lg notebook init creates a notebook skeleton with a worked example; lg notebook new adds a dated entry.
  • lg notebook push is a dry run that lists what would be created, changed, moved or removed. --apply writes the changes.
  • lg notebook check reads 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).
  • 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 ancestry gets cut at creation, so lg sets it again with a PUT;
    • folder status is stored as completed, current and compleation_date.
  • Text and HTML:
    • Labguru rewrites HTML (<br />, &quot;, 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.
  • 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 new names files YYYY-MM-DD-<title>.md and no longer writes a status header.
  • cargo install labguru-cli now 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