Shell Integration

Your services run on random ports, so anything that talks to them needs the current connection details. eph env produces them; this page covers loading them into bash and zsh, fish, JSON-consuming tools, your editor, and your app.

What `eph env` prints

eph env prints the top-level environment variables from your .eph file, with every ${service.property} resolved against the currently running services. It does not print service env.* values; those belong to the service runtime, not your shell.

$ eph up
$ eph env
export DATABASE_URL="postgres://dev:dev@localhost:54321/myapp"
export REDIS_URL="redis://localhost:54322"

Output goes to stdout and all logs go to stderr, which keeps the output clean for eval and piping.

Run eph up before eph env. Interpolation only resolves for running services. If a variable still references a stopped service, shell formats unset that variable and finish with a failing shell statement. This clears a value left by another workspace and makes eval "$(eph env)" return nonzero. JSON omits the unresolved variable. The eph env process also exits nonzero in every format and reports the missing reference on stderr.

Formats

Choose with -f / --format. The default is export.

eph env                     # export (bash/zsh/sh), the default
eph env -f fish             # fish
eph env -f powershell       # PowerShell
eph env -f json             # JSON object

bash / zsh / sh

eval "$(eph env)"

fish

fish needs the output collected so newlines are preserved:

eph env -f fish | source
# or, equivalently:
eval (eph env -f fish | string collect)

PowerShell

eph env --format powershell | Out-String | Invoke-Expression

Out-String collects the lines into one string before Invoke-Expression runs it, the PowerShell equivalent of fish’s | source. Each line is $env:NAME = 'value', with an embedded ' doubled per PowerShell’s own single-quoted-string escaping rule.

JSON

For tools, scripts, and agents that would rather parse structured data than shell syntax:

$ eph env -f json
{
  "DATABASE_URL": "postgres://dev:dev@localhost:54321/myapp",
  "REDIS_URL": "redis://localhost:54322"
}

Pipe it into jq, a .env writer, or your own tooling:

# Pull a single value without hiding eph's exit status in a pipeline
eph_json="$(eph env -f json)" && jq -r .DATABASE_URL <<<"$eph_json"

# Write a .env file for tools that read one
eph_json="$(eph env -f json)" &&
  jq -r 'to_entries[] | "\(.key)=\(.value)"' <<<"$eph_json" > .env.local

Skipping the shell entirely

Two features hand the resolved environment to a process directly, no eval required:

eph run <cmd> runs any command with the resolved variables (plus EPH_* metadata) set: eph run ./scripts/seed.sh. It refuses to start the command if any required service reference is unresolved.
A run= service inherits the same environment at launch, because eph is the one launching it.

Reach for the shell integration on this page when the consumer is your interactive shell or a tool eph does not launch.

Escaping

Values are escaped for the target shell:

export and fish emit the value inside double quotes: export escapes backslash, ", $, and backtick; fish escapes backslash, ", and $ (fish does not treat backticks specially inside double quotes).
powershell emits the value inside single quotes ($env:NAME = 'value'), PowerShell’s literal-string form: nothing is interpolated inside it, so the only character that needs escaping is the single quote itself, doubled (it's becomes it''s).

Literal newlines inside a value are preserved. You do not need to quote values in your .eph file for the shell’s benefit; eph handles escaping.

Auto-loading per directory

You usually want the variables loaded whenever you enter a project.

direnv

Add an .envrc to the project:

# .envrc
if [ -f .eph ]; then
  eval "$(eph env)"
fi

Then direnv allow. direnv loads the variables when you cd in and unloads them when you cd out. If you want services started too, add eph up above the eval, but note that checking containers on every cd can be slow; most people prefer an explicit eph up.

A shell function

Drop this in your shell rc to start and load in one step:

# bash / zsh
ephup() { eph up && eval "$(eph env)"; }

function ephup
    eph up; and eph env -f fish | source
end

Using it in your app

Anything that reads environment variables works once you have run eval "$(eph env)", and an app managed as a run= service gets the variables without even that. If your framework insists on a .env file, generate one from the JSON output (see above); regenerate it after eph up assigns new ports, and keep generated files out of version control.

Recipes puts all of this together: Compose migration, seeding, CI, prewarming for agents, and secrets.