CLI

Manage data with LaminDB instances.

Manage connections

connect

Set a default database for auto-connection.

Python/R sessions and CLI commands will then auto-connect to this LaminDB instance.

Pass a slug (account/name) or URL (https://lamin.ai/account/name), for example:

lamin connect laminlabs/cellxgene
lamin connect https://lamin.ai/laminlabs/cellxgene

Options:

lamin connect [OPTIONS] INSTANCE

Options:
  --help  Show this message and exit.

→ Python/R alternative: connect() the default database or create a database object via DB

info

Show info about the instance, development & cache directories, branch, space, and user.

Manage settings via lamin settings.

Options:

lamin info [OPTIONS]

Options:
  --schema  View database schema via Django plugin.
  --help    Show this message and exit.

→ Python/R alternative: settings()

init

Initialize an instance.

This initializes a LaminDB instance, for example:

lamin init --storage ./mydata
lamin init --storage s3://my-bucket
lamin init --storage gs://my-bucket
lamin init --storage ./mydata --modules bionty
lamin init --storage ./mydata --modules bionty,pertdb

Options:

lamin init [OPTIONS]

Options:
  --storage TEXT  A local or remote folder (`'s3://...'` or `'gs://...'`).
                  Defaults to current working directory.
  --name TEXT     Instance name. If not passed, it will equal the folder name
                  passed to `storage`.
  --db TEXT       Database connection URL. Defaults to `None`, which implies
                  an SQLite file in the storage location.
  --modules TEXT  Comma-separated string of schema modules.
  --help          Show this message and exit.

→ Python/R alternative: init()

disconnect

Unset the default instance for auto-connection.

Python/R sessions and CLI commands will no longer auto-connect to a LaminDB instance.

For example:

lamin disconnect

Options:

lamin disconnect [OPTIONS]

Options:
  --help  Show this message and exit.

→ Python/R alternative: disconnect()

Load, save, create & delete data

load

Sync a file/folder into a local cache (artifacts) or development directory (transforms).

Pass a URL or --key. For example:

# via key
lamin load --key mydatasets/mytable.parquet
lamin load --key analysis.ipynb
lamin load --key myanalyses/analysis.ipynb --with-env
# via registry and --uid
lamin load artifact --uid e2G7k9EVul4JbfsE
lamin load transform --uid Vul4JbfsEYAy5
# via URL
lamin load https://lamin.ai/account/instance/artifact/e2G7k9EVul4JbfsE

Options:

lamin load [OPTIONS] [ENTITY]

Options:
  --uid TEXT  The uid for the entity.
  --key TEXT  The key for the entity.
  --with-env  Also return the environment for a tranform.
  --help      Show this message and exit.

→ Python/R alternative: load(), no equivalent for transforms

save

Save a file or folder as an artifact or transform.

Example:

lamin save my_table.csv --key my_tables/my_table.csv --project my_project

By passing a --project identifier, the artifact will be labeled with the corresponding project. If you pass a --space or --branch identifier, you save the artifact in the corresponding Space or on the corresponding Branch.

Defaults to saving .py, .ipynb, .R, .Rmd, and .qmd as Transform and other file types and folders as Artifact. You can enforce saving a file as an Artifact by passing --registry artifact.

Options:

lamin save [OPTIONS] PATH

Options:
  --key TEXT                      The key of the artifact or transform.
  --description TEXT              A description of the artifact or transform.
  --stem-uid TEXT                 The stem uid of the artifact or transform.
  --project TEXT                  A valid project name or uid.
  --space TEXT                    A valid space name or uid.
  --branch TEXT                   A valid branch name or uid.
  --registry [artifact|transform]
                                  Either 'artifact' or 'transform'. If not
                                  passed, chooses based on path suffix.
  --help                          Show this message and exit.

→ Python/R alternative: Artifact and Transform

create

Create an object.

Currently only supports creating branches and projects.

lamin create branch my_branch
lamin create project my_project

Options:

lamin create [OPTIONS] {branch|project} [NAME]

Options:
  --help  Show this message and exit.

→ Python/R alternative: Branch and Project.

delete

Delete an object.

Currently supported: branch, artifact, transform, collection, and instance. For example:

# via --key or --name
lamin delete artifact --key mydatasets/mytable.parquet
lamin delete transform --key myanalyses/analysis.ipynb
lamin delete branch --name my_branch
lamin delete instance --slug account/name
# via registry and --uid
lamin delete artifact --uid e2G7k9EVul4JbfsE
lamin delete transform --uid Vul4JbfsEYAy5
# via URL
lamin delete https://lamin.ai/account/instance/artifact/e2G7k9EVul4JbfsEYAy5
lamin delete https://lamin.ai/account/instance/artifact/e2G7k9EVul4JbfsEYAy5 --permanent

Options:

lamin delete [OPTIONS] ENTITY

Options:
  --name TEXT
  --uid TEXT
  --key TEXT   The key for the entity (artifact, transform).
  --permanent  Permanently delete the entity where applicable, e.g., for
               artifact, transform, collection.
  --force      Do not ask for confirmation (only relevant for instance).
  --help       Show this message and exit.

→ Python/R alternative: delete() and delete()

Tracking within shell scripts

track

Start tracking a run of a shell script.

This command works like track() in a Python session. Here is an example script:

# my_script.sh
set -e         # exit on error
lamin track    # initiate a tracked shell script run
lamin load --key raw/file1.txt
# do something
lamin save processed_file1.txt --key processed/file1.txt
lamin finish   # mark the shell script run as finished

If you run that script, it will track the run of the script, and save the input and output artifacts:

sh my_script.sh

Options:

lamin track [OPTIONS]

Options:
  --help  Show this message and exit.

→ Python/R alternative: track() and finish() for (non-shell) scripts or notebooks

finish

Finish a currently tracked run of a shell script.

Options:

lamin finish [OPTIONS]

Options:
  --help  Show this message and exit.

→ Python/R alternative: finish()

Describe, annotate & list data

describe

Describe an object.

Examples:

# via --key
lamin describe --key example_datasets/mini_immuno/dataset1.h5ad
# via registry and --uid
lamin describe artifact --uid e2G7k9EVul4JbfsE
# via URL
lamin describe https://lamin.ai/laminlabs/lamin-site-assets/artifact/6sofuDVvTANB0f48

Options:

lamin describe [OPTIONS] [ENTITY]

Options:
  --uid TEXT  The uid for the entity.
  --key TEXT  The key for the entity.
  --help      Show this message and exit.

→ Python/R alternative: describe()

annotate

Annotate an artifact or transform.

You can annotate with projects, ulabels, records, and valid features & values. For example,

# via --key
lamin annotate --key raw/sample.fastq --project "My Project"
lamin annotate --key raw/sample.fastq --ulabel "My ULabel" --record "Experiment 1"
lamin annotate --key raw/sample.fastq --features perturbation=IFNG,DMSO cell_line=HEK297
lamin annotate --key my-notebook.ipynb --project "My Project"
# via registry and --uid
lamin annotate artifact --uid e2G7k9EVul4JbfsE --project "My Project"
# via URL
lamin annotate https://lamin.ai/account/instance/artifact/e2G7k9EVul4JbfsE --project "My Project"

Options:

lamin annotate [OPTIONS] [ENTITY]

Options:
  --key TEXT       The key of an artifact or transform.
  --uid TEXT       The uid of an artifact or transform.
  --project TEXT   A valid project name or uid.
  --ulabel TEXT    A valid ulabel name or uid.
  --record TEXT    A valid record name or uid.
  --features TEXT  Feature annotations. Supports: feature=value,
                   feature=val1,val2, or feature="val1","val2"
  --help           Show this message and exit.

→ Python/R alternative: artifact.features.add_values() via add_values() and artifact.projects.add(), artifact.ulabels.add(), artifact.records.add(), … via add()

list

List objects.

For example:

lamin list branch
lamin list space

Options:

lamin list [OPTIONS] REGISTRY

Options:
  --help  Show this message and exit.

→ Python/R alternative: to_dataframe()

Configure

switch

Switch between branches or spaces.

Python/R sessions and CLI commands will use the current default branch or space, for example:

lamin switch branch my_branch
lamin switch space our_space

Options:

lamin switch [OPTIONS] [[branch|space]] [NAME]

Options:
  --help  Show this message and exit.

→ Python/R alternative: branch and space

settings

Manage development & cache directories, branch, and space settings.

Get or set a setting by name:

• dev-dir → development directory dev_dir

• cache-dir → cache directory cache_dir

• branch → branch branch

• space → space space

Display via lamin info

Examples:

# dev-dir
lamin settings dev-dir get
lamin settings dev-dir set .  # set to current directory
lamin settings dev-dir set ~/my-project
lamin settings dev-dir unset
# cache-dir
lamin settings cache-dir get
lamin settings cache-dir set /path/to/cache
lamin settings cache-dir clear
# branch
lamin settings branch get
lamin settings branch set main
# space
lamin settings space get
lamin settings space set all

Options:

lamin settings [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  cache-dir  Get, set, reset, or clear the cache directory.
  dev-dir    Get or set the development directory.

→ Python/R alternative: dev_dir, cache_dir, branch, and space

migrate

Manage database schema migrations.

Options:

lamin migrate [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  create  Create a new migration.
  deploy  Deploy migrations.
  squash  Squash migrations.

Auth

login

Log into LaminHub.

lamin login prompts for your API key unless you set it via environment variable LAMIN_API_KEY.

You can create your API key in your account settings on LaminHub (top right corner).

After authenticating once, you can re-authenticate and switch between accounts via lamin login myhandle.

Options:

lamin login [OPTIONS] [USER]

Options:
  --help  Show this message and exit.

→ Python/R alternative: login()

logout

Log out of LaminHub.

Options:

lamin logout [OPTIONS]

Options:
  --help  Show this message and exit.

Other

lamin get

Query metadata about an object.

Currently equivalent to lamin describe.

Usage: lamin get [OPTIONS] [ENTITY]

Options:
  --uid TEXT  The uid for the entity.
  --key TEXT  The key for the entity.
  --help      Show this message and exit.

lamin run

Run a compute job in the cloud.

This is an EXPERIMENTAL feature that enables to run a script on Modal.

Example: Given a valid project name “my_project”,

lamin run my_script.py --project my_project

→ Python/R alternative: no equivalent

Usage: lamin run [OPTIONS] FILEPATH

Options:
  --project TEXT    A valid project name or uid. When running on Modal,
                    creates an app with the same name.  [required]
  --image-url TEXT  A URL to the base docker image to use.
  --packages TEXT   A comma-separated list of additional packages to install.
  --cpu FLOAT       Configuration for the CPU.
  --gpu TEXT        The type of GPU to use (only compatible with cuda images).
  --help            Show this message and exit.

lamin io

Import and export instances.

Usage: lamin io [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  exportdb  Export registry tables to parquet files.
  importdb  Import registry tables from parquet files.
  snapshot  Create a SQLite snapshot of the connected instance.