---
name: ship-env
description: Read or write environment variables for a deployed app. Always merges — never overwrites existing vars. Use when you need to set, update, or view env vars for an app without redeploying.
argument-hint: "<app-name> [KEY=VALUE ...]"
---

# ship-env

Read and write environment variables for a deployed app on a ship VPS.
Always merges new values into the existing file — existing vars are never lost.

## Read Config

Load the host from `~/.config/ship/config.json`:

```bash
python3 -c "
import json, os
cfg = json.load(open(os.path.expanduser('~/.config/ship/config.json')))
nick = '<nickname-or-default>'
h = cfg['hosts'].get(nick, cfg['hosts'][cfg['default']])
print(h['host'])
"
```

## Usage Patterns

### View current env vars for an app

```bash
ssh <host> "sudo cat /etc/ship/env/<app-name>.env"
```

Show them to the user clearly. Remind them that PORT, SHIP_NAME, and SHIP_URL are
managed by ship and shouldn't be manually changed.

### Set or update one or more vars

Given vars like `FOO=bar BAZ=qux`, merge them into the existing env file:

```bash
# Read current env
ssh <host> "sudo cat /etc/ship/env/<app-name>.env 2>/dev/null"
```

Then write the merged result back:

```bash
ssh <host> "sudo tee /etc/ship/env/<app-name>.env > /dev/null << 'EOF'
PORT=9013
SHIP_NAME=myapp
SHIP_URL=https://myapp.example.com
FOO=bar
BAZ=qux
EOF"
```

**Merge rules:**
- Start with all existing vars
- Overwrite any keys that appear in the new set
- Add any new keys that didn't exist before
- Never remove existing keys unless explicitly asked

### Delete a var

Only delete a var if the user explicitly asks to remove it by name. Show them the
current value and confirm before removing.

### Restart after changes

After writing new env vars, ask the user if they want to restart the service to apply
them. If yes, use ship-service to restart:

```bash
ssh <host> "sudo systemctl restart <app-name>"
```

## Notes

- Env file lives at `/etc/ship/env/<app-name>.env`
- PORT, SHIP_NAME, and SHIP_URL are written by ship-binary/ship-deploy — don't remove them
- If the env file doesn't exist, the app probably isn't deployed yet — say so
- Use the default host unless a host nickname was specified (e.g. "set FOO=bar on staging")
- After updating, remind the user the service needs a restart to pick up changes