fghj wire
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.
Arguments
Section titled “Arguments”| Argument | Description |
|---|---|
entry | Git 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 already on disk
Section titled “A repo already on disk”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:
cd ~/work/shop/apifghj wire .fghj.yaml # the workspace is ~/work/shopfghj wire . # the sameAn 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:
cd ~/aikido/aikifactory/internal/configfghj wire https://github.com/you/storefront.gitWhen 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.
Workspaces cannot nest
Section titled “Workspaces cannot nest”fghj wire refuses a workspace that overlaps one already wired —
in either direction:
$ fghj wire <url> --workspace ~/work/shop/apiError: /Users/you/work/shop/api is inside the already-wired workspace/Users/you/work/shop. Workspaces cannot nest — wire it separately outsidethat directory, or stop the outer workspace first.
$ fghj wire <url> --workspace ~/workError: /Users/you/work contains the already-wired workspace/Users/you/work/shop. Workspaces cannot nest — wire a directory thatdoesn'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.
Requirements
Section titled “Requirements”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.
What it does
Section titled “What it does”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.
- Tells
fghjdwhich Docker to use: the same one yourdockercommand talks to, worked out the waydockerdoes it —DOCKER_HOST, thenDOCKER_CONTEXT, then your current context, then/var/run/docker.sock. It has to be a unix socket. If it’s a different one from whatfghjdis using,fghjdrestarts onto it andwirewaits until it’s back. This is also how you switch engines: change your docker context, then wire (or runfghj doctor --fix). - Captures your identity — uid, gid,
$HOME, and your SSH agent socket — if$HOMEis set. This is what lets the root-ownedfghjdclone private repos over SSH on your behalf later, without ever holding your credentials itself; see Persistence & workspace store for the full mechanism. - Sends the entry repo and workspace path to
fghjd’s control API, which registers the workspace (and clones the entry repo if needed). - 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
fghjdalready trusts it system-wide, and adds it to your Firefox and Chrome databases, as you, beforewirereturns; anything it couldn’t do is printed as a warning, such as a missingcertutil. Restart a browser that was open. - 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.