CLI

Manage data with LaminDB instances.

Manage the default database

connect

Set the default database instance for this environment.

This command updates your local configuration to target the specified instance: all subsequent Python/R sessions and CLI commands will auto-connect to this 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: create a database object via DB or set the default database of your Python/R session via connect()

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

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.

Transforms: 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.

Plans: Saves agent plans as artifacts with inferred key, kind, and description, e.g.:

lamin save /path/to/.cursor/plans/my_task.plan.md
lamin save /path/to/.claude/plans/my_task.md

How are plans handled?

Plan files are detected by suffix .plan.md (Cursor) or by being under .claude/plans/ (Claude Code). For such paths, the key defaults to .plans/<filename>, the artifact kind is set to plan, and the description is taken from the markdown front matter (name: and overview:). The stored artifact contains only the body (the YAML front matter is stripped).

git: When saving scripts, files will be synced with a git repo if you set:

export LAMINDB_SYNC_GIT_REPO=https://github.com/org/repo

Also see: Sync code with git

Options:

lamin save [OPTIONS] PATH

Options:
  --key TEXT                      The key of the artifact or transform.
  --description TEXT              A description of the artifact or transform.
  --kind TEXT                     Artifact kind (e.g. 'plan', 'dataset',
                                  'model'). Overrides auto-inferred kind for
                                  plan files.
  --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()

Describe, update, annotate & list

describe

Describe an object.

Examples:

# via URL
lamin describe https://lamin.ai/laminlabs/lamin-site-assets/artifact/6sofuDVvTANB0f48
lamin describe https://lamin.ai/laminlabs/lamin-site-assets/transform/uDVvTANB0f48
# via --key for artifacts
lamin describe --key example_datasets/mini_immuno/dataset1.h5ad
# via registry and one of --uid / --name / --key
lamin describe artifact --uid e2G7k9EVul4JbfsE
lamin describe transform --uid Vul4JbfsEYAy5
lamin describe run --uid 6sofuDVvTANB0f48
lamin describe record --name "Experiment 1"
lamin describe project --name "My Project"
lamin describe ulabel --name "My ULabel"
lamin describe branch  # defaults to current branch
lamin describe branch --include comments
lamin describe branch --name main

Options:

lamin describe [OPTIONS] [ENTITY]

Options:
  --uid TEXT            The uid for the entity.
  --key TEXT            The key for the entity (artifact, transform,
                        collection).
  --name TEXT           The name for the entity (record, project, ulabel,
                        branch).
  --include [comments]  Include additional content (e.g. 'comments' for readme
                        and comment blocks).
  --help                Show this message and exit.

→ Python/R alternative: describe()

annotate

Annotate an artifact, transform, or collection.

You can annotate with projects, labels, records, version tags, a readme, a comment, and, for artifacts, with features. For example,

# via registry and --uid for any registry
lamin annotate artifact --uid e2G7k9EVul4JbfsE --project "My Project"
lamin annotate collection --uid abc123 --version "1.0"
# via registry and --name for any registry that has a name field
lamin annotate schema --name my_schema --readme README.md
# via registry and --key for any registry that as a key field
lamin annotate collection --key my_collection --version "1.0"
# via URL for any registry
lamin annotate https://lamin.ai/account/instance/artifact/e2G7k9EVul4JbfsE --project "My Project"
lamin annotate https://lamin.ai/account/instance/schema/123456ABCDEF --readme README.md

Annotating artifacts and transforms works via --key alone:

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 --version "1.0"
lamin annotate --key raw/sample.fastq --features perturbation=IFNG,DMSO cell_line=HEK297
lamin annotate --key raw/sample.fastq --readme README.md  # adds a readme to the artifact
lamin annotate --key raw/sample.fastq --comment "I think we should revisit this, tomorrow, WDYT?"
lamin annotate --key my-notebook.ipynb --project "My Project"

Branch defaults to the current branch:

lamin annotate branch --readme README.md  # current branch; or --name my_branch

Options:

lamin annotate [OPTIONS] [ENTITY]

Options:
  --key TEXT       The key of an artifact, transform, or collection.
  --uid TEXT       The uid of the entity.
  --name TEXT      The name of the entity (record, project, ulabel, branch,
                   feature, schema, space).
  --project TEXT   A valid project name or uid.
  --ulabel TEXT    A valid ulabel name or uid.
  --record TEXT    A valid record name or uid.
  --version TEXT   A version tag for the artifact, transform, or collection.
  --features TEXT  Feature annotations (artifact/transform only). Supports:
                   feature=value, feature=val1,val2, or feature="val1","val2"
  --readme PATH    Path to a README file to attach as a readme block to the
                   entity.
  --comment TEXT   Comment text to attach as a comment block to the entity.
  --help           Show this message and exit.

→ Python/R alternative: artifact.features.add_values() via add_values(), artifact.projects.add(), artifact.ulabels.add(), artifact.records.add(), … via add(), and artifact.version_tag = \"1.0\"; artifact.save() for version tags.

update

Update mutable fields of an entity.

Examples:

lamin update branch --status review                  # current branch
lamin update branch --name my_branch --status draft
lamin update artifact --key my_file.parquet --description "new description"
lamin update project --name my_project --description "updated project notes"

Options:

lamin update [OPTIONS] {artifact|transform|collection|project|branch}

Options:
  --uid TEXT                      The uid for the entity.
  --key TEXT                      The key for the entity (artifact, transform,
                                  collection).
  --name TEXT                     The name for the entity (project, branch).
  --status [standalone|draft|review|merged|closed]
                                  Set branch status (branch only).
  --description TEXT              Set description (artifact, transform,
                                  collection, project).
  --help                          Show this message and exit.

get

Get a field value or describe an object.

If no field flag is passed, this behaves like lamin describe. If a field flag is passed, it reads that field from the resolved entity.

Examples:

lamin get branch --status                # current branch status
lamin get branch --name my_branch --status
lamin get artifact --key my_file.parquet --description

Options:

lamin get [OPTIONS] [ENTITY]

Options:
  --uid TEXT            The uid for the entity.
  --key TEXT            The key for the entity (artifact, transform,
                        collection).
  --name TEXT           The name for the entity (record, project, ulabel,
                        branch).
  --include [comments]  Include additional content (e.g. 'comments' for readme
                        and comment blocks).
  --status              Read branch status.
  --description         Read the description field.
  --help                Show this message and exit.

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()

Manage changes

switch

Switch between branches.

Python/R sessions and CLI commands use the current default branch. Switch it:

lamin switch my_branch  # pass a name or uid of the target branch

To create and switch in one step, pass -c or --create:

lamin switch -c my_branch

To switch to a target space, pass --space:

lamin switch --space my_space

Options:

lamin switch [OPTIONS] [TARGET]...

Options:
  --space       Switch space instead of branch.
  -c, --create  Create branch if it does not exist.
  --help        Show this message and exit.

→ Python/R alternative: branch and space

merge

Merge a branch into the current branch.

Pass the name or uid of the source branch to merge into the current branch.

All SQLRecord objects that have branch_id equal to the source branch’s id are updated to the current branch’s id. Example:

lamin switch main  # swich to the main branch
lamin merge my_branch  # after this all objects on my_branch will be on main

Find more info in the :class:~lamindb.Branch document.

Options:

lamin merge [OPTIONS] BRANCH

Options:
  --help  Show this message and exit.

→ Python/R alternative: merge()

Track 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()

Configure

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