Working with the Lightning CLI to Manage

What a Lightning Studio is (and why it exists)

If you haven’t used one yet, a Lightning Studio is a persistent dev environment in the cloud. Your files stay there. Your environment stays there. You can start it on CPU, switch to GPU when you’re ready to train, and shut it down when you're done.

You don’t provision instances. You don’t configure networking. You don’t manage cloud accounts. You just pick the machine and keep working.

Most people control this from the web UI. And that works fine. But if you already live in your terminal, there’s a faster way to do all of it.

https://pl-bolts-doc-images.s3.us-east-2.amazonaws.com/app-2/develop-1.mp4

Switching between the browser and your terminal

I use an external IDE for my daily work. That means when I'm working in a Lightning Studio, I'm not sitting in the browser-based editor — I'm SSH'd in from my local machine. The studio is just a remote compute backend to me.

That means every time I need to start a studio, stop one, or switch to a different GPU, I'm jumping between my IDE and the browser. I started leaning into the Lightning CLI instead and building a terminal-first workflow around it. Figured I'd share what I've landed on in case it's useful to anyone else working the same way.

If you're using an external IDE, your interaction with Lightning Studios might look something like this:

Open browser
Navigate to lightning.ai
Find your studio
Click start, pick a machine
Wait for it to come up
Switch back to your IDE
SSH in

That works fine. But if you're doing it multiple times a day, it adds up. And if you just need to stop a studio before lunch, you're going through most of those steps again for one action.

Using the Lightning CLI instead of the web UI

Lightning has a full CLI that you might not have tried yet. The web UI is the natural starting point, but once you get your credentials sorted the CLI is genuinely faster for the repetitive stuff.

Installing and authenticating the Lightning CLI

Install the Lightning SDK:

pip install lightning-sdk -U

Then authenticate by running:

lightning login

This opens a browser tab where you sign in. Authentication persists across sessions, so you only need to do it once.

Alternatively, if you prefer environment variables (handy for scripting or CI), grab your credentials from Account Settings > Keys > Programmatic Login on lightning.ai and export them:

export LIGHTNING_USER_ID="your-user-id"

export LIGHTNING_API_KEY="your-api-key"

For convenience you can add those exports to your .zshrc or .bashrc so they persist. A couple of things to keep in mind if you do:

Your API key will be stored in plaintext in that file. Make sure your shell config has appropriate permissions (chmod 600 ~/.zshrc).
If you share dotfiles via a public repo, add your shell config to .gitignore or use a separate file that isn't committed (e.g., source a ~/.lightning_credentials file that stays local).
Rotate your API key periodically from lightning.ai/settings/keys — if it's ever exposed, you can revoke and reissue without downtime.
For a more secure approach, see the secrets manager tip further down in this post.

Core Lightning CLI commands for Studios

Once you're authenticated, the commands follow the pattern lightning studio <action>:

# list your studios

lightning studio list

# start a studio on a specific GPU

lightning studio start --name "my-studio" --machine H100

# stop it when you're done

lightning studio stop --name "my-studio"

# check on running jobs

lightning list jobs

If you work across teamspaces, add the --teamspace flag:

lightning studio list --teamspace "owner/teamspace-name"

Both --name and --teamspace are optional. If you leave them out, the CLI will prompt you interactively to select from your available studios and teamspaces. That's it. Everything from one terminal window.

Learn more about using the Lightning CLI in our docs.

Lightning CLI tips that save time

Here are a few things I do daily that might be worth nicking:

SSH into a Lightning Studio

You can drop into a shell on any running studio straight from your terminal:

lightning studio ssh --name "my-studio"

No browser, no setup, just a direct connection. If you want something more permanent for your IDE, you can also generate an SSH config block:

lightning generate ssh --name "my-studio"

Paste the output into your ~/.ssh/config and now your studio shows up as a regular remote host. VS Code, JetBrains, any editor that supports remote SSH just works. No special plugins, no Lightning-specific extensions. It's just SSH.

Switching between CPU and GPU machines

This is the one that saves me the most time. Start on a CPU while you're setting things up, writing code, installing dependencies. Then when you're ready to actually train:

lightning studio switch --name "my-studio" --machine H100

No need to stop and restart. Your files and environment are still there, you just get different hardware underneath. When you're done training, switch back to CPU so you're not burning GPU hours while you review results.

Copy files to and from a Lightning Studio

Need to push a dataset up or pull results down? Studios don't even need to be running for this. The cp command handles it:

# upload a file

lightning studio cp ./main.py lit://user-123/my-teamspace/studios/my-studio/main.py

# upload a folder (needs -r flag)

lightning studio cp -r ./my-dataset/ lit://user-123/my-teamspace/studios/my-studio/data/

# download from a studio

lightning studio cp lit://user-123/my-teamspace/studios/my-studio/results/ ./local-results/

# download an entire studio

lightning studio cp -r lit://user-123/my-teamspace/studios/my-studio/ ./

The lit:// URL format is: lit://{org-or-user}/{teamspace}/studios/{studio-name}/{path}

No need to configure rsync, set up keys, or figure out port forwarding.

Running Jobs from a Docker image

If you've got a training setup that works locally in a container, you can ship it straight to Lightning without configuring a studio first:

lightning run job --name "training-run" \ --command "python train.py" \ --machine H100 \ --image "my-registry/my-training-image:latest"

Useful when you want reproducible runs without depending on a studio's installed packages.

Learn more about Jobs through the CLI in this tutorial.

https://pl-bolts-doc-images.s3.us-east-2.amazonaws.com/app-2/RunningJobswCLI.mp4

Checking your Lightning CLI configuration

Before you start debugging why something isn't connecting, check the basics:

lightning config show

This tells you what account you're authenticated as, what your default teamspace is, and whether your credentials are valid. Good first step when troubleshooting any connection issue.

Example: daily workflow with the Lightning CLI

Here's roughly what my workflow looks like now:

Morning:

lightning studio start --name "dev-studio" --machine CPU

SSH in from your IDE, write code, test things, install packages.

Ready to train:

lightning studio switch --name "dev-studio" --machine H100

Run the training script. Go get a coffee.

Pull results:

lightning studio cp -r lit://user-123/my-teamspace/studios/dev-studio/outputs/ ./results/

End of day:

lightning studio stop --name "dev-studio"

Four commands. No browser tabs. Everything happens in the same terminal I'm already working in.

Managing Lightning CLI credentials securely

If you already use a secrets manager (1Password, Bitwarden, HashiCorp Vault, etc.), you can wire it up to load your Lightning credentials automatically instead of hardcoding them in your shell config. For example with 1Password CLI:

export LIGHTNING_USER_ID=$(op item get "LightningAI" --field user_id --reveal)export LIGHTNING_API_KEY=$(op item get "LightningAI" --field api_key --reveal)

Any tool that can output a secret to stdout works the same way — just swap in your equivalent command. Drop it in your shell config and credentials get loaded fresh every time you open a terminal. Nothing stored in plaintext, and if you ever need to rotate keys you only update one place.

When to use the CLI vs the Web UI

If you're already working in a terminal most of the day — running training scripts, tailing logs, SSH'd into studios — there's no reason to leave it just to manage your compute. The CLI handles everything the web UI does for the stuff that matters day-to-day. It just takes a bit of initial setup.

The web UI is great for browsing, discovery, and one-off tasks. But for the repetitive start/stop/switch/check cycle, the terminal is faster. Every time.

Working with the Lightning CLI to Manage Lightning Studios