Skip to content

fghj wire

Terminal window
fghj wire <entry> [--workspace <path>]

Wires a workspace into the currently running fghjd, so it shows up in the web UI and can have runs started against it.

ArgumentDescription
entryGit URL of the entry repo, cloned into the workspace if it isn’t already checked out there. Or a repo already on disk — its .fghj.yaml or its folder — whose parent is the workspace.
--workspace <path>Workspace root directory holding sibling repo checkouts. Defaults to the wired workspace you’re standing in, falling back to the current directory.

A repo you already have doesn’t need a URL. Name its .fghj.yaml, or its folder, and the folder it sits in is the workspace:

Terminal window
cd ~/work/shop/api
fghj wire .fghj.yaml # the workspace is ~/work/shop
fghj wire . # the same

An entry that exists on disk is a repo; anything else is a git URL. A workspace’s repos are the folders right under it with a .fghj.yaml, so the file must be at the repo’s root, and every sibling folder with one joins the workspace too. A repo right in your home folder or right under / is refused, since the workspace would be all of it. --workspace may still be given, but it has to be that parent.

The workspace is derived from where you are

Section titled “The workspace is derived from where you are”

--workspace is optional because fghj works out which workspace you mean from your current directory. It asks fghjd for the list of wired workspaces and picks the one your directory is inside — at any depth, so this works from the workspace root, from a repo inside it, or from a subdirectory five levels down inside that repo:

Terminal window
cd ~/aikido/aikifactory/internal/config
fghj wire https://github.com/you/storefront.git

When it derives a workspace you didn’t name, it says so on stderr:

using workspace /Users/you/aikido (derived from the current directory)

Two things it deliberately does not do. It does not guess from the filesystem — no walking up looking for an .fghj.yaml — so the only directories it will ever choose are ones you explicitly wired. And if fghjd isn’t running, or your directory isn’t inside any wired workspace, it falls back to the current directory exactly as it did before, rather than failing.

There is never an ambiguity to resolve, because workspaces cannot overlap: fghj wire refuses a directory that nests with an already-wired one, in either direction.

fghj wire refuses a workspace that overlaps one already wired — in either direction:

$ fghj wire <url> --workspace ~/work/shop/api
Error: /Users/you/work/shop/api is inside the already-wired workspace
/Users/you/work/shop. Workspaces cannot nest — wire it separately outside
that directory, or stop the outer workspace first.
$ fghj wire <url> --workspace ~/work
Error: /Users/you/work contains the already-wired workspace
/Users/you/work/shop. Workspaces cannot nest — wire a directory that
doesn't enclose it, or stop the inner workspace first.

A workspace is the unit fghj graph scans: every sibling directory under it is a candidate repo. Two overlapping workspaces would therefore claim the same repos, derive duplicate node ids and identical *.fghj.internal domains from them, and run two independent reconcilers over one set of containers. Nothing could resolve that afterwards, so it is rejected up front — the same reasoning as the rule that two workspace folders can’t sanitize to the same domain segment.

Re-wiring the same path is fine, and is how you add another entry repo to an existing workspace — it returns the workspace you already have rather than a second one.

The check runs before anything is created, so a rejected wire does not leave a half-cloned entry repo behind.

fghjd must already be running (sudo brew services start fghj on macOS; on Ubuntu the package already runs it; or sudo fghjd in the foreground) — wire fails immediately with a clear error if it can’t find the daemon’s control API.

wire is where setup finishes. Nothing in fghj works before something is wired, so this is where it asks you for what root fghjd can’t find on its own.

  1. Tells fghjd which Docker to use: the same one your docker command talks to, worked out the way docker does it — DOCKER_HOST, then DOCKER_CONTEXT, then your current context, then /var/run/docker.sock. It has to be a unix socket. If it’s a different one from what fghjd is using, fghjd restarts onto it and wire waits until it’s back. This is also how you switch engines: change your docker context, then wire (or run fghj doctor --fix).
  2. Captures your identity — uid, gid, $HOME, and your SSH agent socket — if $HOME is set. This is what lets the root-owned fghjd clone private repos over SSH on your behalf later, without ever holding your credentials itself; see Persistence & workspace store for the full mechanism.
  3. Sends the entry repo and workspace path to fghjd’s control API, which registers the workspace (and clones the entry repo if needed).
  4. Makes sure your browser trusts fghj’s root CA. On macOS the CLI trusts it in your login keychain, for your user only: a password dialog the first time only; cancelling it doesn’t fail the wire, and HTTPS shows certificate warnings until the CA is trusted. On Linux fghjd already trusts it system-wide, and adds it to your Firefox and Chrome databases, as you, before wire returns; anything it couldn’t do is printed as a warning, such as a missing certutil. Restart a browser that was open.
  5. Prints a link to open the workspace in the UI: https://fghj.internal/?workspace=<id>.

Run fghj wire again for the same workspace any time your SSH agent has restarted — the captured identity is refreshed on every call, since the agent socket it points at is only valid for the login session that was live when it was captured.

wire only registers the workspace — it doesn’t resolve its graph or start any containers. Graph resolution happens separately, either via fghj graph or when the UI loads the workspace. Use the UI’s “Download all” and “Switch to flow” (or fghj graph to inspect what would be resolved) as the next steps; see Quickstart.