Sign in

The CLI signs in through the dashboard in your browser. There’s no password. You approve a code, and the CLI gets a session that lasts 30 days.

Sign in

1. Run:

   forculus login

   The CLI opens your browser at the approval page, and prints the same address and a code:

   To sign in, open https://app.forculuslabs.tech/device and enter this code:
   
       PWDS-QSHX
   
   If the page emails you a code and it doesn't arrive within a couple of minutes, check your spam folder and ask for a new one. If that one doesn't arrive either, write to support@forculuslabs.tech.
   
   Make sure the page shows this computer before you approve. Waiting...

2. In the browser, sign in to the dashboard if you aren’t already. Enter your email address, and type the six-digit code you get by email. The code works for 10 minutes. You can also choose Sign in with a passkey, Continue with Google or Continue with Microsoft. See Sign in with a passkey and Sign in with Google or Microsoft.

   If the code hasn’t come in a minute or two, check your spam folder, then choose Send a new code. If that doesn’t come either, write to support@forculuslabs.tech. The page can’t tell you when an email fails to send, so a missing code looks the same as a slow one.

   The first time, the dashboard asks you to agree to the terms of service, the privacy policy, the Data Processing Addendum and the refund policy. You can’t approve a CLI sign-in until you have.

3. Type the code from your terminal.

4. Check the request. The page shows the device, named after your computer, like “forculus CLI on ada-laptop”. It also shows the address and country the request came from, and yours. If they’re on different networks, or in different countries, it says This request came from somewhere else. An IPv4 address is a network of its own, and IPv6 addresses that share their first half are one network. A computer with both IPv4 and IPv6 can send the CLI’s request over one and the browser’s over the other. The page warns of that too, since anyone running forculus login can choose which one it uses. When it happens in the same country, the warning says your own computer can do this. Approve only if you ran forculus login on this computer a moment ago.

5. Choose Approve.

The CLI checks every five seconds, and picks up the approval:

Signed in as ada@example.com. This session lasts 30 days.
You're not in a workspace yet. Make one to deploy into with `forculus workspace create <slug>`. Add `--name` for a display name.

If you’re already in a workspace, the second line lists your workspaces:

Signed in as ada@example.com. This session lasts 30 days.
Your workspaces: acme.

Caution

Only enter a code you got from forculus login yourself. Approving gives that device everything you can do in Forculus for 30 days. If someone sent you a code, choose Deny.

To approve, you need to have signed in to the dashboard in the last 15 minutes. If it’s been longer, the dashboard asks you to sign in again first.

Sign in with a passkey

A passkey signs you in to the dashboard with your fingerprint, your face or your device’s PIN, instead of a code by email. It works for every app shared with you too.

To add one, sign in, open the account menu and choose Sessions. Under Passkeys, choose Add a passkey, give it a name and follow your browser. It asks where to keep the passkey: on this device, on your phone, in a password manager such as iCloud Keychain, Google Password Manager or 1Password, or on a security key. Adding one needs a sign-in from the last 15 minutes. We email you each time a passkey is added to your account.

To sign in with it, choose Sign in with a passkey on the sign-in page. You don’t type your address: your browser shows the passkeys you have for Forculus, and you pick one. A sign-in with a passkey counts as a recent one, so you can approve a CLI sign-in straight after.

• Each account can have up to 20 passkeys, and can add up to 10 in an hour.
• The passkey has to check it’s you, with a fingerprint, face, PIN or password. A security key that only asks for a touch can’t be added.
• We keep the passkey’s public key, an id for it, the name you gave it, the browser that added it and when it was added and last used. The private key never leaves your device or password manager, and we never see your fingerprint or face.
• Passkeys work only on the dashboard’s own address, app.forculuslabs.tech. A page anywhere else, an app included, can’t use them.

Under Passkeys you can rename one, or remove one you no longer use or don’t recognize. Removing a passkey signs out every browser that signed in with it, this one too if it did, and ends its sessions on every app within a minute. It also ends the CLI sessions you approved while signed in with a passkey, cancels a CLI sign-in you approved that way but haven’t finished, and disconnects the AI clients you connected that way. We don’t record which passkey approved them, so they all end, not only the removed one’s. Removing one also needs a sign-in from the last 15 minutes.

If your workspace asks its people to sign in with your company’s sign-in, a passkey doesn’t count for that workspace, the same as a code by email. See Single sign-on.

Sign in with Google or Microsoft

The dashboard’s sign-in page has Continue with Google and Continue with Microsoft under the email form. They work for the dashboard and for every app shared with you.

The first time, we use the email address Google or Microsoft confirms for your account. If you already signed in with a code to that address, it’s the same account, with the same workspaces and apps. After that, your Google or Microsoft account is linked to it, and we go by the link, not by the address.

• Google: the address must be a Gmail address, or one at your organization’s Google Workspace domain. A personal Google account made on a work address can’t sign in this way.
• Microsoft: the address must be on a domain your organization has verified with Microsoft, and the account must be a member of your organization’s tenant, not a guest. Personal Microsoft accounts and accounts with an address their admin typed in and never verified can’t sign in this way. Use a code by email instead.

Approving a CLI sign-in, and a few other things, need a recent sign-in. Signing in again with Google or Microsoft for one of those asks you to sign in to Google or Microsoft again too.

A browser signed in this way is listed under Sessions as signed in with Google or with Microsoft. It lasts 12 hours, like any other.

If your work address is at a domain with its own sign-in, the page sends you there instead of emailing a code. See Single sign-on.

On a server, or over SSH

forculus login --no-browser

The CLI prints the address and the code, and doesn’t open a browser. Open the address on any device where you can sign in, such as your laptop. The approval page will say the request came from somewhere else, which is expected here.

If the code doesn’t work

A code works once, for 10 minutes. A mistyped, used or expired code gets No sign-in is waiting for that code. One network gets 20 tries a minute at starting a forculus login, entering its code, and approving or denying it. Approving or denying an AI client’s connection counts toward the same 20. Past that, the page says Too many tries. Check the code in your terminal and try again in 40 seconds., with the seconds left.

If nobody approves the code within 10 minutes, the CLI stops:

error: The sign-in code expired before you approved it. Run `forculus login` again.

If you choose Deny:

error: The sign-in was denied.

In each case, run forculus login again for a new code.

How many codes you can get

Approving a CLI sign-in, exporting the audit log or a workspace, and deleting your account all need a sign-in from the last 15 minutes, so you may sign in several times in an hour. Reading an app’s database or downloading its files in the dashboard needs one from the last hour. The codes you sign in with count only toward the second limit here:

• 5 unused codes an hour for your address from one network, and 10 from anywhere.
• 30 codes an hour for your address in all, used or not.
• 20 every 10 minutes from one network, for any addresses. An office behind one IP address shares this.

Past a limit, the page says how long to wait:

Too many sign-in codes have been sent. Try again in 42 minutes.

Past the limit from one network, the wait counts from when your codes went out there, so it’s often shorter than an hour. Past a limit from anywhere, it says an hour. Signing in with a passkey, Google or Microsoft doesn’t use a code, so it isn’t limited this way. Passkey sign-ins have a limit of their own: 60 every 10 minutes from one network.

Each network also gets a number of sign-in tries a minute, counted apart for each way of signing in:

• Codes: 20 tries. Asking for a code and typing one in are a try each.
• Passkeys: 40 tries. A passkey sign-in is two of them, its start and its finish, so 20 passkey sign-ins fill the minute.
• Google, Microsoft or your company’s sign-in: 20 tries. Going to the provider and coming back are a try each. Asking for a code is a try here too, since the page first checks whether your address signs in with your company.

Past one, the page says how long to wait, until the oldest try in the minute is over:

Too many sign-in tries. Try again in 40 seconds.

See who you’re signed in as

forculus whoami

ada@example.com
  acme (owner, free plan)

Each workspace line shows your role and the plan. If you have no workspace yet, the line under your email tells you to make one with forculus workspace create <slug>.

Add --json to get the same as JSON, plus when the session ends:

forculus --json whoami

When the session ends

A CLI session lasts 30 days. When it has less than three days left, every command warns you before its output:

Your session ends in 40 hours. Run `forculus login` to start a new one.

With --json, the warning is a line of JSON on stderr instead, like an error:

{"warning":{"code":"session_ending","message":"Your session ends in 40 hours. Run `forculus login` to start a new one."}}

Running forculus login again starts a new session and ends the old one on this computer.

Once a session has ended or been revoked, commands fail with:

error: Your session has ended. It was signed out, revoked or expired. Run `forculus login`.

On a computer that has never signed in, or after forculus logout, they fail with:

error: You're not signed in. Run `forculus login`.

Sign out

forculus logout

Signed out.

This ends the session and removes the token from this computer. If the CLI can’t reach Forculus, it still forgets the token, and warns you that the session keeps working until it expires or you revoke it. If you weren’t signed in, it says You weren't signed in.

To end every CLI session you have, this one too, and disconnect every AI client you connected:

forculus logout --everywhere

Your browser sessions end from the dashboard’s Sessions page. A CLI session can’t sign out a browser.

See and revoke sessions

In the dashboard, open the account menu and choose Sessions. It lists every browser and CLI session you have, where each one signed in, how and when it was last used, and your passkeys. A CLI session is named after its computer, like “forculus CLI on ada-laptop”.

• Revoke ends one session. It stops working on its next request. A revoked browser is signed out of every app within a minute.
• Sign out everywhere ends every browser and CLI session you have, including the one you’re using, and disconnects every AI client you connected. Tick Also revoke my bypass tokens and agent credentials to end those too, in every workspace.

A sign-in your company’s provider made to restore a deleted workspace is listed with the browsers, marked Deleted workspace, with the workspace it can restore or delete for good. Revoke it on its own if you didn’t make it.

Signing out everywhere doesn’t remove your passkeys. If you lose a device that holds one, remove that passkey too.

Revoke a CLI session when you lose a laptop or stop using a machine. Bypass tokens and agent credentials made from it aren’t sessions, so they keep working until they end or you revoke them. If the laptop may be in someone else’s hands, sign out everywhere with the box ticked, or forculus logout --everywhere --tokens.

From the CLI, list your CLI sessions, with the one you’re using marked, and revoke one by its id:

forculus sessions list
forculus sessions revoke <id>

A revoked session stops working on its next request.

Where the session is kept

The CLI keeps your session in config.json in its config directory:

System	Directory
macOS and Linux	~/.config/forculus, or $XDG_CONFIG_HOME/forculus when that’s set
Windows	%APPDATA%\forculus

Set FORCULUS_CONFIG_DIR to use another directory, or pass --config-dir to one command. With a second directory, you can stay signed in as two people at once.

The file holds the API address, your email, the session token and when it ends. On macOS and Linux, only your user can read it. Treat it like a password. Anyone who copies it can act as you until the session ends or you revoke it.

Sessions, agents and scripts

An agent that uses forculus mcp acts as whoever the CLI is signed in as. It has your permissions, and the audit log shows your name. See Use with your AI agent.

For a CI job or a script that calls your app, don’t copy your session. Create a bypass token for the app instead. See Tokens for scripts and machines.

forculus login --dev you@example.com signs in as that email to a copy of Forculus running on your own machine. It’s for people working on Forculus itself. To run your app locally behind our sign-in, use forculus dev. See Local development.

Next steps

• Deploy your first app.