@struct-ai/cli

Struct CLI

Sign in to Struct from your terminal and connect your coding agent (Claude Code, Cursor, Codex, or any MCP client) to Struct. The CLI works the same for people and for agents and scripts.

Full documentation: docs.struct.ai/reference/cli.

Install

Requires Node.js 18 or newer.

npm install -g @struct-ai/cli

Or run it without installing:

npx @struct-ai/cli <command>

Commands

struct login

Signs you in and saves a login for one workspace. The CLI prints the sign-in link first and then waits until you approve, like gh auth login:

• On your own computer it opens the link in your browser. After you approve, the browser returns to a temporary local address on this computer and the CLI finishes.
• Over SSH, on Linux without a display, or when no browser opens it shows a link and a short code instead. Open the link on any device, check that the code matches, and approve. Use --device to choose this yourself.

Device login needs a Struct server that supports it. If yours does not, the CLI prints the browser link instead (and --device fails): open it in a browser that can reach this machine, because approving it returns to a temporary local address here.

Option	What it does
--org <workspace>	The workspace to approve (name or id). Pick it on the approval page.
--device	Sign in with a code on any device.
--no-browser	Print the link without opening a browser.
--with-token	Save a token read from stdin instead of signing in.
--timeout <seconds>	How long to wait for approval (default 900, which is 15 minutes).

Access tokens last one hour; after 90 days without a renewal you sign in again. If you are already logged in to that workspace, the CLI asks whether to sign in again; without a terminal it does not ask (exit 2): run struct logout first.

--with-token does not replace a browser login: if the workspace already has one saved, it exits 1 (oauth_login_exists) and changes nothing. Keep using that login for its own tokens, or run struct logout --org <workspace> first to revoke it, then retry with an independently issued token (logout also ends tokens issued to that login).

With --org, if you approve a different workspace the CLI saves nothing, revokes the new login and exits 1; the browser page says which workspace to choose instead. The approval page does not preselect the workspace yet, so choose it there.

struct whoami

Shows the user, workspace and role of the current login.

struct orgs list and struct orgs switch <workspace>

You can be logged in to several workspaces. Each login belongs to one workspace on one Struct server and is approved separately. orgs list shows the workspaces you have a login for (the current one is marked *). orgs switch selects one; if you have no login for it yet, it starts struct login --org <workspace>.

struct logout

Revokes the current workspace's login on Struct, then removes it from this computer. Your other workspaces and coding agents that signed in themselves stay signed in. Logout also revokes old struct connect grants saved on this computer; use struct mcp install to switch those agents to their own sign-in.

• --org <workspace> logs out of another saved workspace; --all logs out of every workspace on this server (it cannot be combined with --org). A workspace with no saved login, or a name that matches several, is a usage error (exit 2).
• If Struct cannot revoke the login (for example, it cannot be reached), the login is still removed from this computer, but the command exits 1 and says so. Disconnect the Struct CLI in Struct settings to end it.
• A token you added with --with-token is only removed from this computer; revoke it where you created it.

struct mcp install --client <claude|cursor|codex> and struct mcp url

Connects your coding agent to Struct's MCP server. The configuration contains only the server URL: your agent signs in to Struct itself the first time it connects, so no token is printed or stored in its settings.

Client	What struct mcp install does
claude	Runs claude mcp add --transport http --scope user struct <url> (Claude Code, for all your projects).
codex	Adds a [mcp_servers.struct] table to ~/.codex/config.toml (or $CODEX_HOME/config.toml), keeping your settings.
cursor	Adds a struct entry to ~/.cursor/mcp.json, keeping your other servers.

If claude is not installed, the CLI prints the command to run instead. Afterwards, sign in to Struct from your agent: in Claude Code, run /mcp; for Codex, run codex mcp login struct (the --json result names this nextStep). Installing never waits for a browser. Running the install again changes nothing when the entry is already there, and a config file the CLI cannot read safely (for example, invalid TOML or JSON) is left untouched. Add --print to only print the command (or, for Cursor, an install link, and for Codex, the configuration to add) without changing anything. struct mcp url prints the URL for any other MCP client.

struct connect from earlier versions still works but is deprecated: it prints the same URL-only setup and the new command to use.

struct build-agent settings show and struct build-agent settings set

Shows or changes the Fix agent: who writes the fix (struct for the Struct Build Agent, cursor or devin), when Struct opens a pull request (manual: when asked, auto: automatically), and the investigation confidence an automatic pull request needs (4: Very Likely or higher, 5: Definite). show also lists the sources that open pull requests automatically and whether Cursor and Devin keys are saved (never the keys).

struct build-agent settings set --provider struct --trigger auto --min-confidence 5

Any member can run show; set needs a workspace admin (forbidden otherwise). Cursor needs a saved Cursor API key, and Devin a Devin API key and organization ID: until they are saved, set --provider cursor (or devin) exits 1 with cursor_api_key_required, devin_api_key_required or devin_org_id_required. Add the keys in Fix settings in the web app.

struct memory struct-md show, generate and edit

STRUCT.md is the business context every Struct agent reads. show prints its body on stdout (title, version and generation status go to stderr). To edit it safely, take the body and its version from the same show --json answer, so Struct refuses your edit if someone saved in between instead of overwriting their change:

struct memory struct-md show --json > struct-md.json
jq -j .body struct-md.json > STRUCT.md
# edit STRUCT.md, then:
struct memory struct-md edit --file STRUCT.md \
  --expected-version "$(jq .version struct-md.json)" --reason "Added the billing service"

• generate has an agent write STRUCT.md while it is empty (or again after a failed attempt). It needs a workspace admin. Add --wait to wait until it finishes (--timeout <seconds>, default 900, which also bounds each check). Running it while a generation is under way follows that generation.
• edit changes the title (--title) and/or body (--file <path>, or --file - for stdin; at most 4,000 tokens). --reason is saved with the new version. The CLI edits the current version; pass --expected-version <n> (the version from show --json) to refuse the edit if someone saved in between (memory_version_conflict). Edits are refused while a generation is running (struct_md_generating). Editing needs a workspace admin.
• If memories are not turned on for your workspace, these commands exit 1 with memories_not_enabled.

struct artifacts list|show|versions|pdf

Reads the reports Struct saves, such as investigation write-ups and plans. You see the same reports as in the Struct web app: your team's reports and your own private ones.

Command	What it does
struct artifacts list	Lists reports, most recently changed first.
struct artifacts show <id>	Prints the report's Markdown on stdout (title, kind, version and link go to stderr). With --json, prints the whole report.
struct artifacts versions <id>	Lists the report's saved versions, newest first. --before <n> shows older ones; --limit <n> (1 to 100).
struct artifacts pdf <id>	Saves the report as a PDF with its charts; diagrams are left out, with a note in their place. -o <file> (default <id>.pdf, or <id>-v<n>.pdf with --version); --force replaces the file.

list takes --search <words> (words in the latest version; quotes match a phrase and or matches either word), --kind <investigation|incident|postmortem|plan|build_summary>, --since <when> (an age such as 7d or 12h, a date such as 2026-10-01, or a time with a zone), --limit <n> (1 to 100, default 25) and --cursor <cursor> (the nextCursor of the previous page, with the same filters; the next-page hint on stderr includes them). show and pdf take --version <n> to read a saved version instead of the latest. pdf checks the destination before exporting: a missing folder fails with output_dir_missing, a folder as the destination with output_is_directory, and an existing file without --force with file_exists. A report that does not exist and one you cannot see both fail with the error code not_found.

Agents and scripts

• Command data goes to stdout; progress and notices go to stderr.

• --json prints JSON Lines on stdout. The last line is always the final document: the command result, or {"error":{"code":"...","message":"..."}} on failure. Every command prints exactly one line, except struct login (and struct orgs switch when it starts a login): before waiting, it prints what the person has to do, so an agent can pass the link on.

  $ struct login --json
  {"status":"waiting_for_human","method":"browser","url":"https://api.struct.ai/api/oauth/authorize?...","expiresAt":"..."}
  {"status":"ok","loggedIn":true,"method":"browser","workspace":{"id":"...","name":"Acme"},"role":"admin",...}
  

  A device login line also has userCode and verificationUri. The CLI prints a waiting_for_human line only for the link it is actually waiting on: if it cannot open a browser and switches to a device code, it prints only the device line.

• Exit codes:

  Code	Meaning
  0	Success
  1	Error
  2	Usage error
  4	Authentication required

• The CLI only prompts when stdin and stdout are terminals; otherwise a command that needs an answer fails with exit 2 and tells you what to run instead.

• Set STRUCT_PROMPT_DISABLED=1 to also refuse browser approval: a command that would need it exits 4 instead of waiting. struct login still opens the browser (or shows a device code) and waits for approval.

• For unattended runs, set STRUCT_TOKEN. It is used only in memory, never saved, and takes precedence over saved logins. To save a token as a login instead, pipe it to struct login --with-token.

Environment variables

Variable	Default	Purpose
STRUCT_API_URL	https://api.struct.ai	The Struct server to use.
STRUCT_TOKEN	unset	A token to use instead of saved logins (never saved).
STRUCT_PROMPT_DISABLED	unset	Set to 1 to refuse prompts and browser approval.

The CLI reads these only from your environment. It never loads .env files from the current directory, and it prints a notice on stderr when a non-default server is set.

Workspace activation

New workspaces can sign in before a short setup call activates them. Until then, after struct login (and struct whoami) the CLI prints a note on stderr:

Your workspace isn't activated yet. Book a short setup call to activate it:
  <booking link>
Questions? Email [e-mail]

or, if you already booked the call:

Your workspace isn't activated yet. We'll email you after your setup call.
Questions? Email [e-mail]

Sign-in still succeeds. With --json, the result includes activated, setupCallBooked (null when Struct cannot tell yet; no booking advice is shown then) and, when a call should be booked, bookingUrl. A request that Struct refuses because the workspace is not activated exits 1 with the error code account_not_activated and the booking link; with --json, the error also has the link as bookingUrl when Struct sent one.

Credentials

• Saved in ~/.struct/profiles/, one file per workspace and server, with permissions 0600 (only your user can read them). ~/.struct/state.json records the selected workspace for each server.
• Each login is bound to the server that issued it (scheme, host and port) and to one workspace. If you point STRUCT_API_URL at another server, the CLI does not send your saved credentials there; sign in again. Switching workspaces never moves a login to another workspace.
• Renewals are coordinated between CLI processes running at the same time, and files are replaced atomically. A network problem never deletes a login. If the answer to a renewal is lost, the CLI keeps the renewal token it sent and sends it again on the next command, until Struct returns the renewed login or rejects it (then it asks you to sign in again, exit 4). struct logout still revokes such a login.

Security

• PKCE and a state check protect the sign-in code. The local callback listens only on 127.0.0.1, on a port chosen for each sign-in.
• Authenticated requests never follow redirects, so a token cannot be forwarded to another host.
• Settings come only from your environment, never from a repository's .env file.
• Tokens are never printed.

Troubleshooting

• "You are not logged in": run struct login.
• "Struct no longer accepts the saved login" or "Struct rejected the saved login": your access was revoked or expired; run struct login again.
• "Could not renew the saved login": Struct could not be reached, had a temporary problem, or the renewed login could not be saved. Your login was kept; run the command again (no need to log in again): the next command picks up the renewal where it stopped.
• "The saved login is locked by a struct process" (credential_locked): another computer that shares your home directory is using the saved login, or a struct command there was interrupted. The CLI never takes over that lock. If no struct command is running there, delete the lock it names and try again.
• Browser doesn't open: the CLI switches to a code you can enter on any device, or you can copy the printed link into your browser.

Help

Questions or problems: [e-mail] or docs.struct.ai.

License

Copyright Struct. All rights reserved.