strand Download
Guide contents

Settings

Settings → Integrations → Command line → Install strand command installs the bundled companion in ~/.local/bin. Windows adds that directory to your user PATH; open a new terminal afterward. On macOS/Linux, add that directory to your shell PATH if it is missing. The palette's Install strand command… opens this setting. Reinstall the command after upgrading Strand to refresh the installed companion.

Run strand PATH (for example, strand .) to open the containing repository in Strand. A running instance receives the request and comes to the foreground; otherwise the desktop starts and opens the repository after session restore. Quote paths containing spaces. Existing unrelated strand executables in the installation directory are never replaced.

The companion also works headlessly. These commands only read Git state:

strand -C /path/to/repo status --snapshot --json
      strand log -n 50 --json
      strand log --file src/main.rs --json
      strand diff --staged
      strand diff --commit HEAD --json
      strand diff --between main HEAD --json
      strand diff --since main --full-context --json
      strand review --since main --json
      strand review --since main --summary --json
      strand review --since main --path src/main.rs --compact --json
      strand diff-chunk --since main --path src/main.rs --offset 0 --length 65536 --json
      strand schema

--json emits one {schemaVersion: 1, repository, result: {kind, data}} envelope. The data uses Strand's desktop types. Errors produce no stdout and one {code, message} object on stderr: exit 2 for invalid requests, 3 for repository errors, 4 for the 8 MiB output limit, and 5 for output errors. Log limits range from 1–1,000. Full context is available for unstaged diffs and --since; incompatible selectors fail explicitly. Snapshot excludes history; Review includes recent HEAD history and reports its before/after HEAD because concurrent repository changes can occur between reads. No command stages, commits, fetches, pushes or invokes a pager.

For large reviews, start with diff --summary or review --summary to list changed paths without patch bodies. Repeat --path to select up to 32 exact repository-relative paths; review --compact uses three context lines. Summary results have kind diff_summary, selected diff results diff_page, and selected reviews retain the review bundle. Path/summary filtering supports unstaged, staged, and --since comparisons; it does not apply to --commit or --between.

A selected patch page is limited to 4 MiB. If a single patch is larger, use diff-chunk --path FILE: each JSON result contains up to 65,536 exact bytes as an integer array, a total length, next_offset, and a revision token. Request the next section with --offset NEXT_OFFSET --revision TOKEN, keeping the same path, source and context options. A changed patch rejects continuation; restart at offset zero. Concatenate the byte arrays before decoding text, because a section can end inside a UTF-8 character. --full-context includes the whole file, while --staged or --since BASE select the comparison. Binary markers without a revision cannot be continued. The overall 8 MiB JSON output limit is unchanged.

Open the Settings dialog with Mod+,, the gear button in the status bar, or the command palette ("Settings…"). The sections are Appearance, Terminal, Diff, Keyboard, Git, Hosting, Integrations, User actions, AI, Plugins, Updates, and Privacy. Most changes apply live; Git identity, signing, and Azure DevOps Server profiles have explicit save actions.

The sidebar is a keyboard-navigable list: ↑/↓ move between sections, Home/End jump to the first or last, and Escape closes the dialog.

Appearance#

Diff#

Diff options come with a live preview — a sample diff at the bottom of the section re-renders as you change settings. The preview and every diff pane follow Strand's resolved Light, Dark, or System appearance, even when an explicit choice differs from the operating-system theme.

Keyboard#

Every global shortcut in Strand is rebindable here. Shortcuts are grouped by category — General, Navigation, Git, Repository, Appearance — and each row shows the command label with its current binding.

Rebindable defaults include the command palette (Mod+K), destinations Mod+1–Mod+7, Workbench customization (Mod+8), push/pull/fetch/sync, the theme toggle, the repo switcher (Mod+E), and the AI commit-message suggestion (Mod+Shift+M). The full table lives in Keyboard and palette.

Below the rebindable list, a Context shortcuts card documents the fixed, surface-local keys — things like F6 to focus Work tabs, Mod+Enter to commit from the message box, Mod+F to search within the current file or diff, / to search commits, and j/k to step files in the Review queue and Local Changes. These are not rebindable; the card is a reference so you can look them up without leaving Settings.

Repository settings#

Right-click a repository tab or rail icon and choose Repository settings…, or use Repository settings: Identity and signing in Quick Launch. These settings apply to that repository. Identity and Signing have separate tabs; configuration sources and key details expand when needed.

Git#

Network operations, commit/amend and tag creation use your system Git. Credentials, signing programs and GPG/SSH agents come from your existing setup. Strand stores key references, never private keys or passphrases. SSH verification uses Git’s allowed signers file. Commit and tag options offer Use Git setting, Sign this commit/tag, and Do not sign this commit/tag; these choices apply only to that operation. Signed and unsigned commits honor hooks (including core.hooksPath), rejection and message rewrites. A rejection preserves your checkout’s draft and signing choice. Successful hook output is saved in the repository’s Activity history…. Commit options sits beside the Commit button; tag signing is under Advanced options.

Hosting#

Expand GitLab, Bitbucket and GitHub Enterprise setup for sign-in instructions. For a custom host, right-click its remote in the Git sidebar, choose Edit URLs…, and expand Advanced. Select GitHub / Enterprise or GitLab, then click Save provider and refresh Pull Requests. Detect automatically restores public-host detection. This saves repository Git configuration without changing the remote URL. The palette command Settings: Hosting opens this section directly.

Sign in to GitLab with glab auth login --hostname HOST, or to GitHub Enterprise with gh auth login --hostname HOST. API routing and authentication stay scoped to that hostname in the CLI. GitHub's custom API host configuration is honored by gh.

Bitbucket Cloud reads an API-only HTTPS credential for api.bitbucket.org from the system Git credential helper. Use your Atlassian account email as username and a scoped API token as password. Supply read scopes for user, workspace, repository and pull-request data; add repository and pull-request write scopes for creation and review writes. Scopes do not grant repository membership or override branch restrictions. See Bitbucket API token permissions. Git clone/push authentication remains separate. Strand does not save this token in its settings or recovery records.

Hosting is organized into GitHub, Azure DevOps, and Azure DevOps Server accordions. Each summary keeps its connection state visible while the details are collapsed. GitHub shows the account returned by gh; Azure DevOps shows the account returned by az and also requires the azure-devops extension. Refresh reruns these bounded CLI checks. Strand does not read or store either CLI's token.

Azure DevOps Server 2020+ support is optional. Turn on On-premises pull requests to download the latest signed strand-azdo helper whose protocol is compatible with this Strand version. While the helper is being fetched and verified, the status row, install button, and progress bar show that the download is still running. The status row shows the installed helper and protocol versions; Retry installation always downloads and replaces the helper from Strand's current protocol channel, including when the existing binary reports the same version, and installs it only after signature and SHA-256 verification. If installation says no compatible helper release was found, the download for this Strand build's protocol is unavailable. Retry after that helper release is published. An incomplete-release error means its signature or archive is missing. Removing credentials will not repair either download problem. Disabling keeps profiles and credentials. Remove helper and credentials is confirmed separately and removes the binary, profiles, imported certificates, and vault entries even when the installed helper is broken or uses an older protocol.

Each server profile has a display name and an HTTPS collection URL such as https://server/tfs/DefaultCollection. For a standard on-prem HTTPS clone URL, the collection field is optional: leave it blank and Strand derives and saves the collection boundary from the active repository's preferred Git remote. If no standard Server remote can be identified, Strand asks for the URL. It later derives the project and repository from each repository's Git remote. No per-repository project setting is required. Additional HTTPS/SSH prefixes are optional for server aliases; the longest match wins and ambiguous matches are rejected. Cloud dev.azure.com and visualstudio.com addresses are not accepted here; Azure DevOps Services continues to use az.

Choose Personal access token on macOS, Windows, or Linux. The PAT needs at least Azure Code: Read & write scope and is stored only in Keychain, Windows Credential Manager, or Linux Secret Service. It is never written to Strand settings. A PEM CA certificate can be imported for a private PKI; Strand copies and validates it rather than retaining the external path. If PAT login fails, check its scope and expiry and make sure IIS Basic Authentication is disabled, because enabling it prevents Azure DevOps Server PAT authentication. On Windows, Windows identity (Negotiate / NTLM) uses the current login and the Windows trusted-root store instead of a PAT or profile CA. Use Test on a saved profile before opening its pull requests. The Server accordion is green when the verified helper is installed and at least one profile has a stored PAT or selects Windows authentication; this is configuration readiness, while Test performs the actual server connection.

Terminal#

Configure Work's embedded terminals separately from external applications.

Integrations#

User actions#

In Settings → User actions, create, edit, or delete personal commands. Quick Launch (Mod+K) also offers Manage user actions…. Give each action a name, a context (repository, selected branch/tag, or selected working-tree file), a command or program, and one argument per row. Use Add argument or Remove to edit the list. Spaces, quotes and shell metacharacters stay within their row; a blank row passes an empty argument.

Use an installed command such as git, or an absolute executable path without surrounding quotes. Windows actions require a native .exe; to run a script, choose its interpreter as the executable and put the script path in the arguments. Strand adds no shell. Do not embed placeholders inside interpreter code or shell command strings: pass repository values as script arguments. These commands run with your account permissions and can modify files or Git state.

Placeholder Meaning Context
{repo} Absolute working-tree root All
{ref} Full selected ref, such as refs/heads/topic Ref
{oid} Selected ref's commit ID Ref
{file} Validated absolute working-tree file path File
{relativeFile} Selected path relative to the repository root File

Double braces ({{ and }}) produce literal braces. Unavailable placeholders are errors. The working directory is the repository root, or, for file actions, the selected file's parent. Prefer {file} with the latter choice.

For example, a File action named “Inspect file history” can use executable git, repository working directory, and arguments:

log
      -5
      --oneline
      --
      {relativeFile}

Use -- before path operands where the executable supports it. Git actions include Strand's core.fsmonitor and pager overrides in the displayed argument list; no other arguments are added implicitly.

Open Actions on a repository tab, branch/tag row, or single file in the Files tree, then choose the saved action directly. Manage user actions… opens the dedicated settings page. The row you invoke owns the target, including an inactive repository tab. Historical files, directories, and multiple file selections do not offer working-tree file actions. Palette entries named User action: … use the active Work file or explicitly selected branch/tag in All Commits; repository actions use the active repository. Use the existing keyboard context menu (Shift+F10) on branch/tag and Files rows, or search Quick Launch. For a ref palette action, click its branch/tag row to reveal the tip, then press Enter in the graph to select that commit before opening Quick Launch.

Choose Preview command, inspect the resolved executable, numbered arguments, selected target, and working directory, then Run action. A changed selection invalidates the dialog; a moved ref, missing file, or redirected executable/path is checked again before execution. Unsaved editor buffers are not written.

Cancel action, Escape, or closing the dialog stops its process tree. Cancellation does not undo completed changes. Standard output and standard error are displayed separately after the process stops, with status, exit code, and duration. Each stream retains at most 128 KiB of source bytes; excess output or a ten-minute timeout stops the action. Results remain in the dialog until it closes; they are not saved to activity history.

Definitions persist in your personal settings. They are separate from internal Workbench commands and bundled plugins; Strand never loads these action definitions from repository content or community packages.

AI#

Strand can suggest a commit message from staged changes, or all unstaged changes when nothing is staged, draft pull-request text from committed branch changes, and inspect the Review view's exact change set for possible code issues. It has no API key of its own — generation runs through a CLI you already have, on your own subscription. Auth and billing stay entirely in the vendor's CLI; Strand only orchestrates it.

In a packaged desktop build, PATH is recovered from the interactive login shell on macOS/Linux and from the persisted user and machine environment on Windows, then merged with the environment inherited at launch. This finds Homebrew, local-bin, npm, WinGet, and version-manager installs and also supplies runtime commands such as node to npm-installed CLIs. Restart Strand after changing shell startup files or installing a CLI; use the custom path only when you need to override automatic resolution.

To get a commit suggestion, stage some changes and press the sparkle button next to the commit subject field in Local Changes, use Mod+Shift+M, or run "Suggest commit message" from the palette. To draft a PR, use Fill with Codex/Claude Code in the Create PR dialog. To inspect the current Review inbox or pinned-baseline session, use Review with Codex/Claude Code in that toolbar or "Review changes with AI…" in the palette. If the CLI isn't installed or you aren't signed in, the action stays clickable and the hint appears inline. Sign-in starts the provider's browser or CLI flow, and once you complete it you run the action again. If a CLI launcher is present but its packaged executable is broken, Strand keeps that distinct from “signed out” and shows a repair hint beside the form rather than claiming that sign-in opened. Generation failures use concise hints for recognized provider limits, model problems, timeouts, and connection errors. Strand never displays a raw vendor CLI session transcript because it can contain the prompt, repository paths, and patch content.

Strand never runs an automatic provider-status subprocess from Local Changes. Provider checks remain explicit here. Writing generation is user-initiated, uses bounded local context, and does not add Strand telemetry or persist prompts, outputs, or sensitive classifications.

Updates#

The in-app updater covers the macOS app, direct Windows MSI installs, and the Linux AppImage; .deb and .rpm installs are not covered — update them by downloading the new release from GitHub Releases. Microsoft Store MSIX installations instead check Microsoft Store on launch and from this section. When an update is available, Strand notifies you and offers Open Microsoft Store; Microsoft Store remains responsible for downloading and installing the package.

Privacy#

Strand has no telemetry. Reports are user-mediated and open a pre-filled GitHub issue in your browser for review before anything is submitted:

Crashes are always logged locally regardless of the toggle; the section shows the crash-log path and notes that logs can include repository paths, so you can review before sharing.

All settings persist across launches, along with the rest of your session — open tabs, Work pane sizes, each workspace's Custom pane sizes and feature layout, per-repo diff layouts, and workspaces. For the full shortcut reference, see Keyboard and palette.

PreviousKeyboard & Command PaletteNextPrivacy Policy