Command reference

Commands and public flags in the current source tree. Run fed --help or fed <command> --help for the version installed on your machine.

Global flags

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

fed -p backend -p monitoring start    # Multiple profiles
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. A live service whose health check times out produces a warning but does not make fed start fail. See health checks. If any started service has a restart: policy, a background supervisor keeps it running until you fed stop it, even after this command exits. See restart policy for details.

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. Always wins over a restart: policy's background supervisor, so a stopped service stays stopped.

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

fed restart [services...]

Restart services. Defaults to all running services.

Status and logs

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, must pass their health checks within 60 seconds. They are stopped again after the command completes, 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        # Show 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; a bare fed ports does the same.

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 prune

Remove orphaned fed volumes: the named volumes left behind when you rotate an isolation ID, delete a worktree, or abandon a stack. It only ever touches volumes fed created (they carry fed's ownership label) that no container uses, so a live or stopped stack's data is safe. It lists what it found first; in a terminal it asks before deleting, and in a script or agent it deletes nothing without --force.

fed validate

Validate configuration without starting services. Flags typo'd keys with a "did you mean?" hint, without failing on them.

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]

Clear a package's cached copy so the next command that needs it fetches fresh. Without an argument, clears every cached package.

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

Clean up worktree bookkeeping: unregister worktrees whose directories are gone and remove empty leftover directories. It does not delete a worktree that still has files; use fed ws rm for that.

fed ws setup

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

Cloud

fed login / fed logout / fed whoami

Sign in to Service Federation Cloud, sign out, or show the signed-in account. Login prints a sign-in URL you can open on any machine, and opens it in a browser when one is available locally. Approve in the browser and the terminal finishes on its own, over SSH included. --no-browser skips the browser attempt.

fed link org/project

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

fed secrets ls

List the linked project's team development secrets: names and who last updated them, never values. Secrets are set in the dashboard, not the CLI.

Utilities

fed doctor

Check Docker, Compose, Git, and other system requirements. Also reports orphaned fed-managed volumes that fed prune can reclaim.

fed init

Create a starter fed.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 →