Skip to main content

​
outerlayer login

Sign in to your account, and save the login and the gateway address to ~/.outerlayer/config.json.
With no key on stdin, you sign in to your account by browser approval:
  1. login prints an approve link and an 8-character code, such as K7QM-2XPD, and opens the link.
  2. Sign in to the dashboard if needed. Check that the code on the approve page matches your terminal.
  3. Select Approve. There is no factory, organization or permission to choose. login prints Logged in as <your email>.
The link and code expire after 10 minutes. If they do, run login again. A login picks no factory. Run outerlayer init in a repository next: it runs connect, which chooses one. Until then, a command that needs a factory exits 1 and tells you so.
  • The login acts with your role on the factory a command names. Within about five minutes, it shrinks if your role is reduced and stops on a factory you leave.
  • A login cannot create or revoke factory keys, change members, roles, billing or single sign-on, or delete a factory.
  • A second login on the same machine revokes the token it replaces.
  • To see or revoke every machine signed in to your account, open Security on your profile (/profile/security). The CLI logins list has a Revoke button for each.
  • A factory key always wins over a login. A key from OUTERLAYER_API_KEY or apiKey in the config file is sent instead, so CI and runners keep acting as their key. See Credential resolution.
From an agent or a script. When stdout is not a terminal, login does not wait. It prints one JSON document and exits 75:
Give the url to the person. Run the check command until it stops exiting 75. The waiting login’s one-time key is kept in ~/.outerlayer/login-pending/ until it finishes or expires. A factory key you already have. Pipe it on stdin, as in the second synopsis line. Use this in CI and on runners. The key is saved as apiKey, never accepted as a flag, and never printed.
  • login reads stdin to the end, so secret managers that prompt work.
  • After 1 second with no input, it says on stderr that it is waiting for a key.
  • A pipe silent for 30 seconds counts as nothing piped, and login starts a browser login.
  • A piped key is checked for shape only. The first sync proves it.
See also: Quickstart, API keys, What leaves your machine.

​
outerlayer connect

Choose the factory this repository’s work goes to.
Run it in a repository after login. outerlayer init runs it for you. With a login, it takes the first rule that gives one answer:
  1. --factory.
  2. The repository’s saved connection, while you can still use that factory.
  3. The one factory the repository is linked to.
  4. The one factory you can use.
  5. On a terminal, it asks. With no terminal, it exits 1 and lists each factory with the --factory value to pass.
It always says what it chose and why, and how to change it. connect never links a repository. When the repository is not linked to the chosen factory, it saves the connection anyway and exits 2 with the link to fix it:
If the gateway cannot answer whether the repository is linked, connect says it could not check and exits 0. When .outerlayer/ holds files that are not committed, a connect that succeeds ends with a line telling you to commit and push them. The factory reads your policy from the default branch, so no check runs on pull requests until it is there. With a factory key, the key decides the factory. connect changes nothing, makes no network call and exits 0. --factory naming another factory is an error. Where the connection is stored. In the repository’s shared git directory, at outerlayer/connection.json, readable by you only. Every worktree of the clone shares it. It is never committed, and it goes away with the clone. Two repositories on one machine can go to two factories. How a login’s factory is chosen, including what overrides the connection, is in Credential resolution.

​
Automatic connection

work build, emit artifact and the other commands below connect automatically when one factory fits:
  • outerlayer work build, work list, work status, work remove and work pr
  • outerlayer emit <name>, emit artifact, emit criteria, emit finding and emit findings
They connect when all three hold:
  • You are logged in.
  • The repository has no saved connection.
  • Exactly one factory fits by rules 2 to 4 above.
They never ask. They print one line to stderr naming the factory and why, save the connection, and carry on. They skip the link check, so outerlayer doctor still reports a missing link. When more than one factory fits, they refuse and list each factory with the --factory value to pass to outerlayer connect.
The line changes only which factory this checkout uses. It never links a repository. A command given --repo, such as work build --repo acme/app, chooses the factory by the links of the repository it names, not by the checkout’s own remote. So running it from another checkout, such as a factory repository, still reaches the factory that builds acme/app. The connection is saved for the checkout you ran it from. These never connect on their own, so run outerlayer connect before them:
  • The other work subcommands: claim, renew, release, comment, threads, open-pr and link-session.
  • sync, live upload and the MCP server.
See also: Quickstart, Connect a repository, Capture commands.

​
outerlayer logout

Revoke this machine’s login and remove it.
logout deletes accountToken and dashboard from the config file. A factory key (apiKey), its appId and every repository’s saved connection stay. See also: What leaves your machine.

​
outerlayer sync

Upload the sessions launched with OUTERLAYER_WORK, incrementally.
The summary line counts sessions uploaded and skipped, with the reason: The hooks run sync --quiet in the background after each agent turn and at session end, at most once every five minutes, once login has saved credentials. Set "autoSync": false in the config file to stop that. See also: Launch a session, What leaves your machine.