Teamspace Drive

Every teamspace has one Drive: the shared filesystem behind your Studios, your uploads, and everything your jobs write. Four commands work on it from the terminal.

All four address the Drive with lit:// URLs, so start there.

lit:// URLs

A lit:// URL names a location in a teamspace Drive. It has two forms.

Long form — name the org that owns the teamspace:

lit://<org>/<teamspace>/<folder>/<path>

Every teamspace belongs to an organization, so <org> is always an organization name — including the personal organization created for your own account.

Short form — three slashes instead of two, for the teamspace you are already working in:

lit:///<folder>/<path>

Inside a Studio, that is the Studio's own teamspace. Anywhere else it is the teamspace you selected with lightning config set teamspace. The two forms are otherwise identical, so every example below works either way.

Top-level folders

A Drive's contents are grouped into top-level folders, and every lit:// URL names one — with a single exception: lightning ls may stop at the teamspace root to list the folders themselves. There is no default folder, so any other command whose URL stops at the teamspace fails.

Most of these only exist once you have created something, so run lightning ls on the teamspace root (lit://acme/research/) to see what yours actually has.

A few kinds of storage sit on network mounts that no storage API serves — EFS connections and folders, Filestore folders, and high-performance volumes, which appear beside the folders in lightning_storage/. Those are listed like anything else, but cp, ls and edit cannot reach inside them. Read and write them from a Studio or Job instead.

Creating and deleting folders

lightning cp -r into lightning_storage/, s3_folders/ or gcs_folders/ creates the named folder if it does not exist — Lightning provisions those itself, so a name is all it needs. The connection folders work the other way: s3_connections/, gcs_connections/ and r2_connections/ point at buckets you supply credentials for, so the name must already exist and copying into an unknown one fails.

lightning rm -r on one of these names deletes the folder or connection itself, not just what is inside it. That is also why -r is required: a connection is a folder, so a plain lightning rm on one is an error. Some types are torn down asynchronously, so the name can linger in a listing for a moment after the command returns.

lightning cp -r ./checkpoints lit:///lightning_storage/scratch/run-7/   # creates "scratch" if needed
lightning rm -r lit:///lightning_storage/scratch                        # deletes the folder itself

lightning cp

Copy between your machine and the Drive. Exactly one side must be a lit:// URL; the other is a local path. The direction follows from which is which.

lightning cp SOURCE DESTINATION [-r] [--cloud-account <name>]

Upload — local source, lit:// destination:

lightning cp ./file.txt lit://acme/research/uploads/file.txt
lightning cp -r ./results/ lit:///uploads/results/

Download — lit:// source, local destination:

lightning cp lit://acme/research/uploads/file.txt ./file.txt
lightning cp -r lit:///studios/my-studio/results/ ./results

Copying between two lit:// URLs is not supported; one path must be local.

lightning ls

List a Drive folder without downloading anything.

lightning ls PATH [-r] [--json]

lightning ls lit://acme/research/                  # top-level folders in the Drive
lightning ls lit://acme/research/uploads/reports
lightning ls -r lit:///uploads/reports
lightning ls --json lit:///uploads/reports | jq '.[].path'

lightning rm

Delete a file or, with -r, a folder.

lightning rm PATH [-r] [-f]

lightning rm lit://acme/research/uploads/file.txt
lightning rm -r lit:///uploads/reports/

lightning edit

Change a Drive file in place. The file is downloaded, opened in your editor, and re-uploaded when you save and close — only if the contents actually changed.

lightning edit PATH [--editor <command>]

lightning edit lit:///studios/my-studio/notes.txt
lightning edit lit://acme/research/uploads/config.yaml --editor "code -w"

Job artifacts

A Studio-backed job keeps what it writes in the Drive under jobs/<job-name>, where it stays until the job is deleted. That makes it addressable like anything else:

lightning ls -r lit://acme/research/jobs/my-job
lightning cp lit://acme/research/jobs/my-job/metrics.json .

A job running a container image keeps nothing unless it was launched with artifacts_destination, and when it was, its artifacts live at that destination rather than under jobs/.

In the SDK, job.artifacts_uri gives you the right URL either way, and job.list_artifacts() and job.download_artifacts() do the same reads in Python — see the Jobs SDK reference.

A multi-machine job has no single artifact folder, because every machine writes its own — under jobs/<job-name>-<rank> when the job is Studio-backed.

Deprecated commands