CLI reference

Everything below connect is a piece you can run on its own. connect signs in and keeps the machine online; project add adds a directory or a repository as a project. Commands that act on a project take --on to say which location they mean, so the same commands serve this machine, another machine of yours, and Exeora Cloud.

connect#

A few flags for the cases it cannot guess:

The first time connect runs at a terminal it asks where projects should be cloned on this machine, and saves the answer as projects-root. A machine that was told through exeora config or EXEORA_PROJECTS_ROOT is never asked, and neither is one running under --json or without a terminal.

While connect is running, Exeora asks the operating system to keep both the machine and its display awake. The request covers relay reconnects and is released when the command exits. It does not override an explicit sleep request or closing a laptop lid. If the operating system cannot create the request, Exeora warns once and continues connecting.

login#

exeora login opens a browser on this machine. On a server, a VM, or any SSH session where that cannot work, pass --code. The terminal prints a URL and a short code. Open the URL on a phone or laptop, type the code from the terminal, and approve Exeora. Do not paste a code you did not just see on a machine you control: that would sign their machine in as you. exeora connect --code does the same thing on the way to staying online.

gateway#

Exeora is open source, so https://exeora.dev is a default rather than an address. exeora gateway use https://your.example.com points this machine at your own deployment and stores the choice, so every later command follows it with no flag and no variable. exeora gateway prints the active one and where it came from; exeora gateway reset goes back to the hosted one. exeora login and exeora connect take --gateway to do the same thing on the way past.

One gateway is active at a time. Switching forgets the machine registration, the projects and the session belonging to the previous one, because a device id issued by one gateway's database means nothing to another. The CLI lists what it is about to forget and asks before it does. It also checks that a gateway actually answers at the address before touching anything, so a typo leaves a working setup exactly as it was.

project#

exeora project add
exeora project add ~/code/api
exeora project add owner/repo
exeora project add owner/repo --on cloud
exeora project add https://git.example.com/you/repo.git

project add takes a directory on this machine, the address of a repository, or owner/repo on GitHub. A directory is registered where it is; one that exists is read as a directory whatever else its name could mean. A repository is cloned into this machine's projects folder, or put on Exeora Cloud with --on cloud. With no target, the current directory is added. When it is not inside a checkout, the command runs at a terminal and GitHub is connected, a repository is picked from a list instead, and the command asks where it should live.

What makes a checkout the same project on another machine is its remote. Adding a checkout whose remote is already a project of your account joins that project as one more location, and the command says so. A name that belongs to a different repository on another machine is refused with slug_taken rather than moved. See how a second machine joins a project.

exeora project list
exeora project locations api
exeora project locations add api --on desktop
exeora project locations remove api --on desktop
exeora project default api --on desktop
exeora project credential api --token-stdin < token.txt
exeora project credential api --remove
exeora project remove api

--on takes a machine's name, that name as a slug, here for the machine the command runs on, or cloud. project list prints every project of the account with its repository, and under it each location with its state and its path, the default marked with *. locations add clones nothing: the first workspace made in that location brings the copy. locations remove and project remove ask first unless -y is given, and never delete files on your machines. Removing a machine of yours as a location forgets that copy and leaves every other location alone. Removing Exeora Cloud as a location, or removing the project, destroys its instances there.

Only project remove removes a project. locations remove on the only location of a project that has a repository leaves the project, which lives nowhere until it is given a place again, and the command says how. project list prints such a project with nowhere in place of its locations, and Exeora Cloud that holds no instance for the project root with the state no instance. A directory with no remote cannot lose its only location: the command is refused and names project remove.

project credential is for a repository that is not connected to GitHub. The token arrives on standard input, never as an argument, so it stays out of shell history and process lists. Instances created or retried from then on use it; one already running keeps the token it was set up with.

workspace#

exeora workspace create feature/name
exeora workspace create feature/name --from main
exeora workspace create feature/name --project api --on desktop
exeora workspace create feature/name --project api --on cloud

Without --on, or with --on naming this machine, workspace create makes a native Git worktree here, from the current workspace's HEAD, registers it under the project and synchronizes its stable id with the gateway. A project this machine is a location of and holds no copy of yet is cloned into the projects folder first. With --on naming another location the workspace is made there: a worktree on that machine, which has to be connected, or an instance on Exeora Cloud, which the command waits for.

Use --from <ref> to choose another base, or --reuse-existing-branch when the branch already exists. --project selects a project when the command is not run inside one. --path places a worktree on this machine somewhere other than the default root, and cannot be combined with --on.

workspace list shows the workspaces of the project the current directory is in, with the machine that holds each one, or of every project when the directory is in none. --project names another project and --all lists every project.

attach connects an existing workspace on this machine without taking ownership of its creation. detach only disconnects it from Exeora. remove runs Git's worktree removal and refuses uncommitted changes unless --force is present; branches are kept unless --delete-branch is requested, and then Git's safe branch -d is used. A workspace on Exeora Cloud is removed by destroying its instance, after asking unless -y is given. A workspace on another machine of yours is removed there, where its files are, and the command says which machine that is.

A gateway outage leaves a safe pending record and exeora sync retries it.

config#

exeora config get projects-root
exeora config set projects-root ~/code/exeora
exeora config unset workspace-root

EXEORA_PROJECTS_ROOT and EXEORA_WORKSPACE_ROOT override them for one environment. A relative path given to set is resolved against the current directory before it is stored.

device#

exeora device list, or exeora machine list, prints every machine of the account: the ones you connected, with the projects each holds, and the instances Exeora Cloud runs, with the project and workspace each was made for. The machine the command runs on is marked.

sync#

exeora sync brings this machine's configuration in line with what the gateway holds. It forgets a machine that was deleted from the dashboard, mirrors the projects this machine is a location of, and retries the workspace registrations and removals that a gateway outage left pending. It also tells Exeora the repository of projects the gateway knows only as a directory, which is every project added by a CLI older than 0.18.0. Run it once on such a machine: until the gateway knows the repository, the project cannot live anywhere else.

What a deleted machine forgets is its own configuration. A project with a repository stays in the account, in its other locations or nowhere. Run exeora connect to register the machine again, then exeora project add . in a checkout to make it a location of its project.

git-credential#

exeora git-credential [--project <id>] get|store|erase

A git credential helper, run by git rather than by you. For get it reads git's request from standard input and answers with a short-lived token for the repository of the project, made by the gateway for a project connected to GitHub. Without --project the project is found from the host and path git names, which needs credential.useHttpPath to be true. store and erase do nothing: the token is made on request and kept nowhere.

A helper that fails must fail quietly. On any failure it prints nothing to standard output, exits with success and says why on standard error, so git moves on to the next helper. It answers only over https and only for the host git asked about.

You do not configure it. When the CLI clones with this helper and the machine's own git could not have read the repository, it writes the helper into that repository's .git/config, for that host only, so later fetches and pushes work. Your global git configuration is never changed.

cloud#

Exeora Cloud has no commands of its own: it is a location, reached with --on cloud on the commands above. The older exeora cloud commands still work as aliases, so scripts written for them keep running. See Exeora Cloud.

exeora connect --cloud is the other side: what an instance itself runs as a service. It reads a machine token from disk instead of signing in, holds the instance awake while it works, and answers the gateway's wake requests. Since 0.19.0 it also runs the project's scripts there, and gh on the instance is signed in as you. There is no reason to run it on a laptop.

init#

Interactive by default. Pass --yes to take the flags as given and ask nothing, and --force to replace a file that already exists.

exeora init --yes --mode allow_list --allow "npm,git *" --deny "sudo,rm *"

--tools takes the same comma-separated form. See what a project allows for what the values mean.

prompt#

Writes the prompt to stdout and nothing else, so it pipes. Every MCP client already receives this over the wire; the command is for the ones that never ask. Pass --account for the variant that explains choosing between projects.

exeora prompt > AGENTS.md

See the agent prompt for what it says and the other three ways to get it.

upgrade#

exeora upgrade downloads the newest stable GitHub release for this operating system and CPU, verifies its published SHA-256 checksum, and safely replaces the running executable with it.

The upgrade needs write access to the executable. Installations made with the standard scripts live in a user-owned directory, so they do not normally need elevated privileges.

Machine-readable output#

--json makes status, logs, device list, project list, project locations, workspace list and config get print one JSON document instead of drawing on the terminal. Errors become JSON on stderr with a non-zero exit, so a caller piping stdout into a parser gets either valid JSON or nothing. Under --json nothing is asked, so a command that removes something or destroys an instance needs -y.

exeora logs --json | jq '.[] | select(.status == "error")'

Three of those documents changed shape when projects gained locations, because they stopped describing one machine and started describing the account:

• project list prints the account's projects as the gateway lists them, not only the ones on this machine. Each carries repoUrl, defaultBranch, mcpUrl and locations, and each location its slug, name, kind, state, localPath and whether it is the default. Since 0.18.1 each project also carries nowhere, true for one that has no default machine: its locations are then empty, or hold Exeora Cloud in state no instance. project locations carries the same key, and project locations remove answers with it.
• device list prints every machine with its kind, local or cloud, its state and thisMachine. A machine of yours lists the projects it holds; an instance names its project and workspace.
• workspace list prints every workspace of the listed projects wherever it is, with machine, deviceId, cloud, projectSlug, thisMachine and syncState. The project roots, which the table always shows, are added with --roots.

Every key that 0.17.0 printed is still printed, with the value it had, beside the fields above. A path on another machine is null in those keys, so a script does not open a directory of the same name on this one.

project add answers with project and location, which is created, joined or updated, and with adopted when a repository was placed on this machine: true for a checkout that was already in the projects folder, false for a fresh clone.

status carries accountMcpUrl alongside each project's own mcpUrl, on both the signed-in and signed-out shapes, so a script can find the URL that covers every project without having to build it.

On connect, which never finishes, it prints one JSON object per line as things happen, which is what a supervisor or a log collector can read as it arrives. In that mode there is nobody at the terminal, so confirmations go to the dashboard instead. The awake event reports whether system and display sleep prevention is active, with a reason when the operating system rejected the request.

Where things are stored#

The refresh token goes to the OS keychain. Machines with no secret service, which is most Linux servers and CI containers, get a 0600 file under $XDG_CONFIG_HOME/exeora/ instead, and the CLI says so when it happens. Everything else is plain JSON; exeora status prints the path.

EXEORA_GATEWAY_URL points the CLI at a different gateway for one shell, without overwriting the stored value it outranks. For anything longer lived, including a self-hosted deployment you use every day, exeora gateway use is the one that sticks.

The one thing it asks for#

On the third interactive run, if the GitHub CLI is installed and signed in, Exeora asks once whether to star the repository, and does it with gh if you say yes. It checks first whether you already starred it, in which case it never asks. Say no and it goes quiet for a long while, asks a second and last time, then never again.

The question needs a real terminal, so it never appears under --json, in CI, in a script, or on a machine without gh. EXEORA_NO_STAR_PROMPT=1 turns it off outright. Left unanswered for thirty seconds it takes the default, which is yes, and prints the one command that undoes it.