Quickstart

Create a workspace, store your first secret, and run a command against it - start to finish in about ten minutes.

Before you start

You need an account on shortspan.dev - or a self-hosted deployment, in which case read Installation first and come back here. Everything below works on the free tier.

Signing up walks you through four short setup steps: name a workspace, tell us a little about yourself, create a first project, and optionally invite people. That is covered in First-run setup; this page picks up once you have a workspace and a project.

1. Install the CLI

bash

# macOS and Linux
curl -fsSL https://shortspan.dev/install.sh | sh

# or with Go, from source
go install github.com/ft72/shortspan/cli@latest

bash

shortspan version

Prints the version, commit, and build date. A build that reports `dev` was compiled without release metadata - fine locally, but it will not participate in version-blocking.

Full instructions, including Windows and self-hosted hosts, are in Installing the CLI.

2. Sign in

bash

shortspan login

The CLI prints an eight-character code and a URL. Open the URL in a browser where you are signed in, confirm the code matches, and approve. The CLI is polling and will pick up the token within a few seconds.

The token goes into your operating system keyring - Keychain on macOS, Secret Service on Linux, Credential Manager on Windows. It is not written to a file.

bash

shortspan whoami

Confirms who you are signed in as and which host you are talking to.

3. Choose where you are working

Almost every command acts on a project, so the CLI keeps an active organization and project rather than making you name them each time.

bash

shortspan org list
shortspan org use acme

shortspan project list
shortspan project use production

4. Store a secret

bash

shortspan secret set STRIPE_SECRET_KEY --template plain

Prompts for the value without echoing it. Use `--value` or `--file` in scripts.

Secrets are typed. plain is an opaque string; there are also templates for environment variables, JSON documents, TLS certificates, SSH logins, database connections, AWS credentials, and kubeconfigs. shortspan secret templates lists them, and Secret templates documents each one's fields.

bash

shortspan secret list

Lists keys and metadata. It never prints values - that takes a separate command and a separate permission.

5. Use it without ever seeing it

This is the part worth internalising. There are two ways to get a secret out, and only one of them is a good habit.

bash

# Injects the value as an env var into one process. Nothing is printed,
# nothing reaches your shell history, nothing lands on disk.
shortspan secret run STRIPE_SECRET_KEY -- ./deploy.sh

bash

# Prints the plaintext to stdout. Requires the secrets:reveal ability,
# is rate limited separately, and is recorded as a reveal in the audit log.
shortspan secret get STRIPE_SECRET_KEY

6. Group what belongs together

An application needs a dozen environment variables, not one. A secret group names that set so it can be injected as a unit.

bash

shortspan secret group create api-production --environment production
shortspan secret set DATABASE_URL --template env --group api-production
shortspan secret set REDIS_URL --template env --group api-production

# Every secret in the group, injected into one process.
shortspan run api-production -- npm start

7. Register a server

Servers, databases, AWS accounts, and Kubernetes clusters are registered in the console under Infrastructure, because doing so means handing over a credential and that is worth doing deliberately.

Once a server is registered with the alias prod-web-1, anyone with developer access to the project can connect without ever holding its key:

bash

shortspan ssh prod-web-1

# or across a whole tagged fleet
shortspan ssh exec @web "systemctl status nginx"

Databases work the same way, including through a bastion:

bash

shortspan db main
shortspan db main --via prod-web-1
shortspan db main --print

What to read next

Core conceptsWorkspaces, projects, grants - the model behind what you just did.InfrastructureRegistering servers, databases, and cloud accounts properly.Using the CLI in CIToken-based auth for machines with no keyring and no browser.Roles and permissionsWho can do what, before you invite anyone.

Something here wrong or missing? Tell us.