CLI DOCUMENTATION

dotlet is a CLI tool for syncing and versioning your dotfiles. It transforms your configuration files into modular units called islets, enabling seamless synchronization across machines with versioned history.

DOTLET CLI V0.1.0

01.

Installation

Requirements

Node.js 20 or later

pnpm (recommended)

shell

$ pnpm install -g dotlet

curl

shell

$ curl -sL https://dotlet.app/install.sh | sh

Verify

shell

$ dot --version
dotlet v0.1.0

02.

Overview

The dotlet CLI lets you push configuration files from any machine to the cloud, organize them by device, and pull them back on another machine. Every push creates a new version, so you can always roll back or inspect history through the web interface.

The CLI is available as two equivalent binaries: dotlet and dot. All examples in this documentation use dot for brevity, but dotlet works identically.

shell

$ dot <command> [options]

Commands:
  login              Sign in to your Dotlet account
  logout             Log out of your Dotlet account
  push <path>        Push a file or directory as an islet
  pull <islet>       Pull an islet
  list               List islets for a device
  device             Manage devices

Authenticate the CLI with your dotlet account. This initiates an OAuth2 device authorization flow -- a URL is opened in your browser where you approve the CLI.

shell

$ dot login

The command displays a verification URL and a one-time code. Once you approve in the browser, the CLI stores the access token locally and you're ready to push and pull.

output

dotlet login
┌─────────────────────────────────────────────┐
│ URL      https://dotlet.app/oauth/device    │
│ Code     ABCD-1234                          │
│ Expires  about 15m 0s                       │
└─────────────────────────────────────────────┘
✔ Browser opened (0.3s)
⠋ Waiting for authorization...
✔ Login successful. CLI is now authorized.

04.

Logout

Terminate the current session and clear local authentication tokens. This removes the stored credentials from your machine.

shell

$ dot logout

output

✔ Logged out successfully.

05.

Push

Push a file or directory as an islet to your device. Each push creates a new version. If the content hasn't changed, the file is marked as unchanged.

shell

$ dot push <path> [options]

Arguments

<path>

File or directory to push. Can be a relative or absolute path.

Options

-d, --device<name>

Device to target. Overrides the configured default device.

-n, --name<name>

Custom islet name. This name will be used as path for the islet instead of the current path.

-a, --absolute

Store file paths as absolute instead of relative. Useful when you want to restore files to their exact original location.

-m, --message<text>

Message describing this islet version, similar to a commit message.

-v, --visibilitypublic | private

Whether the islet is visible to others. Defaults to the device's visibility.

Examples

shell

# Push a single config file
$ dot push ~/.config/ghostty/config

# Push an entire directory
$ dot push ~/.config/nvim

# Push to a specific device with a message
$ dot push ~/.zshrc -d laptop -m "added aliases"

# Push with absolute path storage
$ dot push ./.vscode/settings.json --absolute

# Push with a custom name
$ dot push ~/.config/ghostty/config -n ./ghostty/config

# Push as private
$ dot push ~/.ssh/config -v private

06.

Pull

Pull an islet and write the files to disk. By default, files are restored to their original paths. Existing files are skipped unless --force is used.

shell

$ dot pull <islet> [options]

Arguments

<islet>

Name of the islet to pull. Accepts short form, full form, or a web URL. See Pull Targets below.

Options

-f, --force

Replace files that already exist locally. Without this flag, existing files are skipped with a warning.

-p, --path<path>

Path to write pulled files into. Overrides the original file paths.

-d, --device<device | username/device>

Device to pull from. your device name, or username/device for a specific account. Only valid with short-form islet names. Cannot be combined with full-form targets or URLs.

-v, --version<version>

Version of the islet to pull. Can also be specified inline with "?v=" in the target string.

Pull Targets

The <islet> argument accepts three formats:

Short form

Just the islet name. Use your default device or -d / --device with a device name (your account) or username/device to target a specific account without using the full username/device:islet form.

shell

$ dot pull ~/.zshrc
$ dot pull ./nvim/init.lua
$ dot pull ~/.zshrc?v=rev2
$ dot pull ~/.zshrc -d laptop
$ dot pull ~/.zshrc -d alice/laptop

Full form

Includes the username and device. No --device flag needed.

shell

$ dot pull alice/laptop:~/.zshrc
$ dot pull alice/laptop:./nvim/init.lua?v=rev1

Web URL

A full URL from the dotlet web interface. Cannot be combined with --device.

shell

$ dot pull "https://dotlet.app/alice/laptop/islet?n=~/.zshrc"
$ dot pull "https://dotlet.app/alice/laptop/islet?n=./nvim/init.lua&v=rev1"

Examples

shell

# Pull and restore to original path
$ dot pull ~/.zshrc

# Pull and overwrite existing files
$ dot pull ~/.zshrc --force

# Pull to a custom directory
$ dot pull ./nvim/init.lua -p ~/backup/init.lua

# Pull a specific version
$ dot pull ~/.zshrc -v rev3

# Short form with explicit username/device (-d)
$ dot pull ~/.zshrc -d alice/laptop

# Pull from another user's public islet (full form)
$ dot pull alice/laptop:~/.zshrc

07.

List

List all islets for the selected or specified device. --device accepts a device name on your account or username/device to list another user's device. Running dot with no subcommand is equivalent to dot list.

shell

$ dot list [options]
$ dot              # same as dot list

Options

-d, --device<device | username/device>

Device to list islets for: your device name, or username/device for a specific account. Uses the configured default device when omitted.

Examples

shell

$ dot list -d personal
$ dot list -d alice/laptop

output (your device)

✔ Found 3 islets
personal

  ‣ .zshrc
  ‣ nvim/init.lua
  ‣ .config/ghostty/config

output (username/device)

✔ Found 2 islets
alice/laptop

  ‣ .zshrc
  ‣ nvim/init.lua

08.

Device

Manage devices: list, create, or choose a default. Running dot device with no subcommand is equivalent to dot device list.

shell

$ dot device [subcommand] [options]

device list

List all devices. The current default device is highlighted.

shell

$ dot device list [options]
$ dot device           # same as dot device list

-u, --username<name>

Username of the account to list devices for. Defaults to the signed-in user.

output

✔ Fetched 2 devices

  ◉  personal  public
  ◯  work      private

device create

shell

$ dot device create <device name> [options]

<device name>

Name of the new device.

-v, --visibilitypublic | private

Whether the device is visible to others. Defaults to public.

Examples

shell

# Create a public device
$ dot device create laptop

# Create a private device
$ dot device create work -v private

device use

Set a device as the default. Subsequent commands that accept --device will use this device when the flag is omitted.

shell

$ dot device use <device name>

<device name>

Name of the device to set as default.

Example

shell

$ dot device use laptop

output

✔ Default device set to laptop

09.

Workflows

Common end-to-end scenarios combining multiple commands.

First-time setup

shell

# Install
$ pnpm install -g dotlet

# Authenticate
$ dot login

# Create a device for this machine
$ dot device create macbook

# Set it as default
$ dot device use macbook

Push your configs

shell

# Push individual files
$ dot push ~/.zshrc
$ dot push ~/.gitconfig

# Push a config directory
$ dot push ~/.config/nvim

# Push with a version message
$ dot push ~/.config/ghostty/config -m "updated font size"

Restore on a new machine

shell

# Install and login on the new machine
$ pnpm install -g dotlet
$ dot login

# Set the device
$ dot device use macbook

# List what's available
$ dot list

# Pull everything back
$ dot pull ~/.zshrc
$ dot pull ~/.gitconfig
$ dot pull ~/.config/nvim --force

Pull from another user

shell

# Pull a public islet using the full form
$ dot pull alice/laptop:~/.zshrc

# Pull and save to a specific path
$ dot pull alice/laptop:nvim/init.lua -p ~/nvim/init.lua