Command reference

The fed command surface on one page. Run fed --help or fed <command> --help for full details.

Global flags

These flags apply to all commands and normally appear before the subcommand. --verbose is also accepted after it.

fed -p backend -p monitoring start    # Multiple profiles
fed -e staging status                 # Non-default environment
fed -c custom.yaml start              # Custom config file

Starting & stopping

fed start [services...]

Start services. Defaults to the entrypoint if no services are specified. Starts dependencies first, polls configured health checks during startup, then backgrounds.

fed start                        # Start entrypoint services
fed start api gateway            # Start specific services
fed start --watch api            # Watch mode with auto-restart
fed start --replace              # Reclaim occupied ports
fed start --isolate              # Isolate, then start

fed stop [services...]

Stop services. Defaults to all running services.

fed stop                         # Stop everything
fed stop api                     # Stop a single service

fed restart [services...]

Restart services. Defaults to all running services.

Observability

fed status

Show service status.

fed logs <service>

View logs for a service.

fed logs api                     # View full log
fed logs api -f                  # Tail logs
fed logs api -n 50               # Last 50 lines

fed tui

Launch interactive TUI dashboard.

fed top

Show resource usage for all services. Refreshes periodically.

Scripts

fed run <script> [-- args...]

Run a named script. Services in depends_on are started first and, if the script started them, stopped again after it completes — or fails, or is interrupted with Ctrl+C ("borrow or own"). Services that were already running (e.g. via fed start) are left running, as are all services when the script sets keep_services: true. See Scripts.

fed run db:migrate
fed db:migrate                          # Shorthand (if no command collision)
fed test:integration -- -t "auth"       # Pass arguments after --
fed run e2e --output passthrough        # Surface service logs (use in CI)

Isolation

fed isolate enable

Enable isolation mode — every declared type: port parameter gets a random port, while direct image: containers and their named volumes use an isolation ID. Literal ports and Compose's path-derived project namespace are not remapped. See Isolation.

Run it first in a new worktree, before any other fed command — it persists, so everything after it is isolated. See Isolation.

fed isolate disable

Disable isolation mode — clear persisted allocations and return to the directory's normal ports and container namespace.

fed isolate status

Show current isolation state and port allocations.

fed isolate rotate

Re-roll ports and isolation ID. Requires services stopped or --force.

Ports

fed ports list

Show current port allocations. Alias: fed ports ls.

Lifecycle

fed install [services...]

Run install hooks. Defaults to all services with an install field.

fed build [services...]

Run build hooks (shell and Docker).

fed clean [services...]

Run clean hooks and remove configured, fed-scoped Docker volumes. With no service arguments, includes every service with a clean hook or a volume, removes orphaned fed processes and containers, and clears persisted ports and lifecycle markers.

fed validate

Validate configuration without starting services.

Docker

fed docker build [services...]

Build Docker images only (skip shell build hooks).

fed docker push [services...]

Push built images to registry.

Packages

fed package list

List cached packages.

fed package refresh [source]

Re-fetch packages. Without an argument, refreshes all packages in the current config.

fed package clear

Clear the entire package cache.

Workspaces

Alias: fed ws for fed workspace.

fed ws new <branch>

Create a worktree for an existing branch, or a new branch with -b.

fed ws new my-feature -b    # Create new branch + worktree
fed ws new main             # Worktree for existing branch

fed ws list

Show all worktrees with service status. Alias: fed ws ls.

fed ws cd <name>

Switch to another worktree.

fed ws rm <name>

Stop services and remove a worktree. Alias: fed ws remove.

fed ws prune

Remove worktrees for deleted branches.

fed ws setup

Install shell integration (zsh or bash) into your shell rc file — one-time, enables auto-cd for fed ws new and fed ws cd.

Cloud

fed login / fed logout / fed whoami

Sign in to Service Federation Cloud (browser flow; --no-browser prints the URL instead), sign out, or show the signed-in account.

fed link org/project

Bind the checkout to a Cloud project. Writes .fed/cloud.yaml, which is meant to be committed.

fed secrets ls / fed secrets set NAME

Team development secrets. Both take a subcommand-local --env flag (default development) — note this is separate from the global fed -e flag, which does not apply here:

fed secrets ls --env staging
printf '%s' "$VALUE" | fed secrets set STRIPE_KEY --env staging

set reads the value from stdin so it never lands in shell history.

Utilities

fed doctor

Check system requirements (Docker, etc.).

fed init

Create a starter service-federation.yaml.

fed completions <SHELL>

Generate shell completions. Supported shells: bash, zsh, fish, elvish, powershell.

fed completions zsh > ~/.zfunc/_fed

Debug

fed debug state

Show full state tracker contents.

fed debug ports

Show port allocation internals.

fed debug circuit-breaker <service>

Show circuit breaker state for a service.

Next: Team secrets →