dotstate / docs / first-time setup

First-time setup.
A single evening.

Run dotstate with no arguments and it launches into a guided setup. This page walks through the same flow — useful if you'd rather understand the choices before you make them.

Launch

$ dotstate

The TUI opens in welcome mode. There's one important decision to make up front: how do you want to store your dotfiles?

Choose a repository mode

◐

Create for me (GitHub)

dotstate creates a private dotstate-storage repo on your GitHub account and manages it for you. Requires a GitHub token. The easiest path if you don't already have a dotfiles repo.

◒

Use my own repository

Point dotstate at any existing git repo you own — on GitHub, GitLab, Bitbucket, self-hosted Gitea, or anywhere else. Uses your system's git credentials. No token required.

GitHub-managed mode

Pick this if you want dotstate to handle the repo creation. You'll be asked for a GitHub token — dotstate supports both fine-grained and classic tokens.

Fine-grained tokens (recommended)

Create one at github.com/settings/personal-access-tokens/new.

Permission	Access	Why
Administration	Read & write	To create the `dotstate-storage` repository
Contents	Read & write	To sync your dotfiles to and from the repository
Metadata	Read-only	Included automatically by GitHub

For initial setup, grant access to All repositories. Once dotstate has created the storage repo, regenerate the token and restrict it to that repo only.

Classic tokens

Create one at github.com/settings/tokens. Required scope: repo (full control of private repositories).

Storing the token

You can provide the token in two ways:

Environment variable: export DOTSTATE_GITHUB_TOKEN=your_token — useful in CI and dotfiles scripts.
Config file: pasted during setup and stored in ~/.config/dotstate/config.toml with user-only permissions.

Bring-your-own mode

Pick this if you already have a dotfiles repo anywhere, or if you'd rather not give dotstate a token. Provide the clone URL — SSH or HTTPS — and dotstate clones into ~/.config/dotstate/storage/.

# Any of these work:
git@github.com:you/dotfiles.git
https://gitlab.com/you/dotfiles.git
https://git.selfhosted.example/you/dotfiles.git

Your system's git credentials are used for push and pull, just as they are for any other repo.

Create your first profile

After the repo is ready, dotstate prompts for a profile name. Pick something descriptive — personal, work, or the hostname of this machine. You can always add more later. See profiles & inheritance for how to organize multiple.

Adopt your first files

The main menu opens. Navigate to Manage Files, and pick the dotfiles you want to adopt. dotstate moves each into the repo and creates a symlink in its place — so your tools keep finding them at the usual paths, and version control watches for changes.

Sync

Go to Sync with Remote — or run dotstate sync — to commit, pull, and push. That's it. Your dotfiles are now backed up and ready to be pulled down on another machine with dotstate activate.

Read the quick start for a five-minute tour, or jump to package management to track CLI tools alongside your dotfiles.

First-time setup.A single evening.