Skip to main content

​
crewship server

crewship server manages server profiles: named targets stored in a single ~/.crewship/cli-config.yaml, each with its own server URL, auth token, and default workspace. One config can address dev1/dev2/dev3, staging, and prod, and you switch between them without juggling config files or environment variables.
Each profile’s token is bound to that profile’s host. Selecting a profile can never send another instance’s bearer to the wrong server — the same host-mismatch guard that protects --server applies (see crewship login).

​
Subcommands

​
Quick start

The minimum is one login per instance — login --profile <name> --server <url> creates the profile if it doesn’t exist. If no default profile is set yet, it also becomes current, so you don’t need a separate server add (logging into another profile later does not re-point an existing default):
crewship server list then shows:
Single-server users need none of this — plain crewship login keeps writing the top-level config exactly as before. Profiles are opt-in.

​
How the active profile is resolved

For every command, the active profile is chosen in this order (first match wins):
  1. --profile <name> flag — one-off override.
  2. CREWSHIP_PROFILE env var — scopes to a shell.
  3. Directory match — directory_profiles in the config (see below).
  4. current — the persisted default set by crewship server use.
If no profile is selected, the CLI falls back to the legacy top-level server/token/workspace fields (single-server mode), so existing configs keep working unchanged. The selected profile’s server, token, and workspace then flow through the normal resolution chain. An explicit --server still overrides the dial target; CREWSHIP_SERVER is only consulted when the active profile does not already define a server URL (and a host mismatch still fails if the token was minted for a different host).
Because a directory match (layer 3) outranks the persisted current default (layer 4), crewship server use <name> can appear to silently “not work” when run inside a directory-mapped clone — the directory binding keeps winning. crewship server current surfaces this explicitly when it happens (directory override for <dir> — persisted default (server use) is "<name>"), and crewship server list’s active marker shows *d instead of plain * for a directory-resolved profile. If you actually want the persisted default to win in that directory, crewship server remove the directory binding (or edit directory_profiles in the config) rather than repeating server use.

​
Directory auto-select

directory_profiles maps a directory to a profile, so the CLI picks the right target automatically based on where you run it. Bind a directory from the CLI with server add --dir (no YAML editing) — . means the current directory:
That records:
Now running crewship inside /work/crewship_2 (or any subdirectory) automatically targets dev2 — no --profile flag, no env var. The longest matching path wins, and matching is on path boundaries (so /work/crewship_1 never matches /work/crewship_10). server remove also prunes a profile’s directory bindings, so no cwd resolves to a deleted profile. This is the native replacement for shell hooks that exported CREWSHIP_SERVER/CREWSHIP_CONFIG based on $PWD.

​
Migrating from CREWSHIP_CONFIG

Earlier multi-instance setups pinned a separate config file per directory via the CREWSHIP_CONFIG env var. Profiles fold all of those into one file: CREWSHIP_CONFIG still works (it points the CLI at a specific file) and remains useful for fully isolated configs, but it is no longer required to target multiple instances.

​
See also