Skip to content
Shortspan

Search documentation

Find a page by title, section, or summary.

Configuration

The config file, the active organization and project, and the environment variables that override both.

The config file

One YAML file, at ~/.config/shortspan/config.yaml. The directory is created with 0700 permissions.

~/.config/shortspan/config.yaml
api_host: https://shortspan.dev
active_org: acme
active_project: 9f2c1e04-7b3a-4d51-8e6f-2a9c4b1d7e30
active_project_name: Production
KeyMeaning

api_host

Which deployment to talk to. Also the keyring lookup key for your token.

active_org

The organization slug commands act in.

active_project

The project id, not its slug - project routes bind by id.

active_project_name

Cached for display, so listing your context needs no request.

Reading and writing it

bash
shortspan config list
shortspan config get api_host
shortspan config set api_host https://shortspan.internal.example.com

Config commands run before the authentication gate, so config set api_host works before you have signed in anywhere. Requiring a token in order to set the host would strand every self-hosted user.

The active context

Almost every command acts on a project. Rather than naming it each time, the CLI keeps a current one.

bash
shortspan org list        # organizations you belong to
shortspan org use acme

shortspan project list    # projects in the active organization
shortspan project use production

project use takes a slug and stores the resolved id, so renaming a project in the console does not silently break your local context.

Without an active project you get a direct instruction rather than a confusing 404:

text
no active project. Run 'shortspan project use <slug>'

Environment variables

These override the config file for a single invocation, which is what a CI runner needs when it cannot write one.

VariableEffect

SHORTSPAN_TOKEN

Use this token instead of the keyring. logout cannot remove it and will tell you so.

SHORTSPAN_API_HOST

Talk to this host instead of the configured one.

SHORTSPAN_NO_UPDATE_CHECK

Suppress the background update notice. Set it in CI.

SHORTSPAN_CONFIG_DIR

Keep the config file, auth cache and update check in this directory instead of ~/.config/shortspan. Use it to hold a second context - a local server, a customer account - without moving HOME, which would take the OS keychain with it.

SHORTSPAN_PLAIN

Drop panels, colour and tips. Output stays tabular and stable for scripts. Same as --plain.

SHORTSPAN_FORCE_STYLE

Render the full terminal presentation even when output is redirected, for capturing documentation or a screenshot. --plain still wins.

bash
# A one-off against staging without disturbing your saved context
SHORTSPAN_API_HOST=https://staging.internal shortspan secret list

There is also a --host flag on every command, which does the same thing for one invocation.

Using the CLI in automation

  1. 1

    Mint a scoped token

    In the console under API tokens, or with shortspan token create. Give it only the abilities the job needs - a deploy job usually needs secrets:read and nothing else.

    bash
    shortspan token create ci-deploy --abilities secrets:read --abilities ssh:use
  2. 2

    Store it as a secret in your CI provider

    The token is shown once, at creation. There is no way to read it again afterwards.

  3. 3

    Set the context explicitly in the job

    A CI runner has no saved config, so name the organization and project every run rather than relying on a default.

    bash
    shortspan org use acme
shortspan project use production
  4. 4

    Inject rather than reveal

    Use run or secret run so values never enter the job log. CI providers mask known secret values, but they cannot mask something they were never told about.

    bash
    shortspan run api-production -- ./deploy.sh

Every request from CI is audited with the token identity and source address, so a token behaving unusually is visible in the audit log alongside human activity.

Exit codes

Commands that wrap another process - run, secret run, aws --exec - propagate the wrapped process's exit code rather than replacing it. A failing deploy script fails the build.

CodeMeaning

0

Success.

1

The CLI itself failed - not authenticated, resource not found, permission denied.

*n*

The wrapped process's own exit code, passed through unchanged.

Diagnostic output goes to stderr, so shortspan secret get X > file writes only the value.

Something here wrong or missing? Tell us.