> ## Documentation Index
> Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Ara CLI

> The ara command line and the Ara Device worker it installs, which runs approved Ara work on your computer.

## August 11, 2026 — Fast, safe Device checkpoints

* A provider-neutral Ara turn now retries a bounded zero-output inference socket
  close under the same idempotency key. Once any model event has streamed, Ara
  never replays the request. This recovers a transient connection drop between
  a tool result and the next model round without duplicating output or work.
* Persistent Ara Cloud workspaces now keep their shared repository cache on a
  detached HEAD and use the same repository lock for materialization and
  cleanup. A continuation that starts from a default branch such as `main` no
  longer fails because the cache checkout owns that branch. Preparation
  failures also name their bounded stage without exposing paths, repository
  credentials, or command output.
* Internal code now calls clone/fetch/worktree bootstrapping **workspace
  materialization**. It is runtime plumbing after Ara chooses a target, not the
  retired repository Environment, setup-key, plugin, image, or readiness gate.
  Sessions remain repository-optional; `.ara/runbook.md` remains the only
  repository-owned development guide.
* Ara CLI 0.2.39 gives every claimed Device operation heartbeat a four-second
  deadline and bounded retries. A stalled network request can no longer consume
  the full 30-second operation lease before Hands starts. Successful retries
  report their retry count, and a lease recovery now emits a run- and
  operation-scoped warning that distinguishes a stall before the first Device
  event from a later interruption.
* Ara CLI 0.2.38 makes repeated repository work on a Mac fast without sharing
  mutable working trees. A new per-run checkout can copy Git objects from an
  earlier Ara-managed checkout only after its canonical root, raw origin, HEAD,
  and non-symlink boundaries verify; it then fetches the requested remote and
  checks out an independent branch. Device status also refreshes the enrolled
  organization's name and slug through the Device's own proof-bound identity,
  so it remains readable even when the CLI is currently signed into another
  organization.
* Ara CLI 0.2.37 starts physical Bash without loading the user's login or
  interactive shell profiles. Device commands now reach the managed checkout
  directly instead of waiting on unrelated shell startup hooks, and active
  Hands control polls every two seconds so target switches and cancellation
  settle promptly.
* A Cloud session can now create a repository-bound successor directly on an
  online authorized Device root. It no longer has to attach that root to the
  old immutable repository first; neutral roots stage Ara's exact managed
  checkout, while roots explicitly bound to a different repository remain
  rejected. Cloud Bash results also preserve Git object IDs only after a hidden
  live-checkout verification, matching Device output without weakening secret
  redaction.
* Clean read-only work on a Mac no longer uploads the same full repository
  checkpoint after every shell result and again during finalization. Ara first
  compares a private temporary-index tree with origin state captured before
  model tools become available, then skips
  only clean reproducible work, untouched scratch work, or an already verified
  identical state. Dirty files and committed-but-unpushed work still take the
  fully verified checkpoint path, and an invalid probe falls back safely to a
  full checkpoint.
* Exact Git commit and tree IDs learned by that trusted internal probe now stay
  readable in Device results such as `git rev-parse HEAD`. Unknown long
  token-shaped values continue to be redacted.
* A request such as "use this repository without asking me to pick one" now
  keeps its explicitly named repository. Ara only starts repository-neutral
  scratch work for a direct no-repository instruction, not for a request to
  avoid legacy setup questions.
* Sending a Device task immediately after opening the composer now joins the
  connected-repository request already in flight, just like Ara Cloud. An exact
  repository name cannot fall through to scratch merely because its overview
  was still loading.
* Device and repository intent rules are shared by the web app and API. Changes
  to those shared rules now trigger the production API deployment as well as
  the web deployment, preventing split behavior between new tasks and
  continuations.
* Return wording such as "move this same task back to my online MacBook Pro"
  now resolves before the continuation starts. With one admitted Device, Ara
  creates the Device-bound child directly instead of booting a Cloud
  coordinator that has to discover the Mac and create another session.
* A direct relative request such as "use the repository I worked in most
  recently" now binds that newest connected repository before the run starts,
  even when sent immediately from a cold Cloud or Device composer. This history
  is personal: only sessions the signed-in member created or steered count, so
  a teammate's newer run cannot select their repository. Pinned display order
  does not override actual recency, and identical GitHub/GitLab paths keep the
  provider from the recent session. Stale browser history no longer prevents a
  fresh server-history lookup, and the local Acme guest uses its own membership
  history. General prose about recent repository activity or project artifacts
  still does not silently choose a checkout.
* An initially selected Mac now says **Preparing Mac** while its managed
  workspace attaches. **Retrying Mac** is reserved for explicit recovery, and
  Brain no longer probes session history to rediscover the current run's
  computer, repository, or environment.

## August 10, 2026 — Connecting a session to your computer actually runs there

* Repositories are now context, not a prerequisite. Web and public API sessions
  can start as scratch work with no connected repository, and a disconnected
  repository from old recent-session history can no longer be selected by
  inference. Ara removed the former repository Environment setup, required-key
  and required-plugin readiness gates, authored setup scripts, snapshot builds,
  and their background repair jobs; agents discover dependencies and use
  workspace secrets as part of the task instead. Secrets are now only personal
  or workspace-wide; the deprecated repository secret scope and empty
  "required key" placeholders are gone.
* Device handoffs now have an explicit four-coordinate contract: Device, local
  path, repository origin, and branch. Source checkouts remain on the selected
  computer rather than in PostgreSQL; normal moves use the Git branch, while a
  verified checkpoint bundle protects full Mac working-tree state during
  recovery into Ara Cloud.
* Ara now treats requests about "my Mac" or a named local machine as Device
  work: it checks the current workspace's available devices and granted roots,
  attaches an unambiguous match, then finds the relevant checkout inside that
  root. A task no longer needs to begin with a repository selection: the new
  task composer infers a named or recently used repository from the request,
  while an explicit scratch/no-repository request always beats recency. A named
  computer can be attached from ordinary prose or an @ capability mention; the
  availability rows remain read-only rather than becoming target pickers.
  Sending immediately while the repository list is still loading now joins that
  same in-flight load before routing, instead of treating the temporary empty
  list as a request for a scratch workspace. Repository switches in a session
  are also remembered for the next new task.
* Natural availability wording from the composer, such as "my online MacBook
  Pro," now routes to that Device instead of falling through to Ara Cloud. The
  desktop app also invokes Device-only lifecycle actions through Ara's private
  internal command boundary; the deleted public `ara local` command is no
  longer a hidden desktop dependency.
* A deploy-time retry now keeps the same managed Mac checkout when its run,
  path, origin, and branch still verify, even if Ara's private bootstrap-policy
  marker changed between releases. Ara never resets the checkout or accepts a
  different origin or branch. Cloud handoff also probes an exact-name sandbox
  collision replacement before using it and recreates one acknowledged-but-dead
  workload automatically.
* Read-only shell probes that use temporary files now appear as shell activity
  in the session trace, not as repository edits. Redirects to durable workspace
  files continue to appear as edits.
* A run that Ara already routed to a specific computer and repository now waits
  on that in-progress Device attachment through its physical shell instead of
  redundantly listing, reconnecting, disconnecting, or creating another session.
  Canonical `ara_*` control calls also appear as Ara MCP activity in the trace,
  never as file edits merely because an argument contains a repository path.
* A reply that explicitly names a different connected repository now creates
  one correctly bound continuation before the agent starts. Ara keeps the
  requested Cloud or Device target independently and drops the old
  repository's branch, issue, and pull-request metadata, instead of making the
  agent list Devices and create multiple target sessions. Ara Cloud is treated
  as the already attached included computer, so a Cloud reply starts with its
  shell directly.
* Session activity recognizes typed `ara_*` calls even when the event title
  includes serialized inputs. Read-only probes that clean up files under the
  system temporary directory also stay shell activity rather than appearing as
  source edits.
* The new-task screen now shows a read-only overview of the computers and
  repositories available to Ara, including the workspace's included Ara Cloud
  computer. Rows are deliberately not selectors: Ara still infers both targets
  from the request, while dedicated links let members add another computer or
  repository. While connected repositories are loading, the overview now says
  so instead of briefly claiming the workspace has none.
* When several eligible devices or roots exist, Ara does not pick one
  arbitrarily or block the follow-up. It keeps the conversation safe in Ara
  Cloud while Brain resolves the named machine through the audited Device
  tools. Repository discovery on a local device also rejects unbounded
  recursive fallbacks before they reach the device.
* When a request names a connected repository for Device work, Ara stages its
  managed checkout with the workspace's repository access and verifies that
  working directory first. It scans a granted personal root only when the user
  explicitly asks for a pre-existing checkout or path, or when the staged
  origin does not match. This keeps ordinary Cloud-to-Device repository
  switches out of personal folders and avoids a redundant filesystem search.
* The Ara Device background worker now reconnects after transient timeouts,
  deploy-time 502s, and dropped sockets with bounded backoff. launchd also
  restarts an unexpectedly exited worker while the device remains enrolled.
  A local telemetry-spool failure cannot interrupt that reconnect loop.
* Ara CLI 0.2.33 closes interrupted REPL clients before shutting down a Hands
  session. A cancelled run can no longer leave Chromium holding the Device's
  single execution slot and make every later Mac handoff report that the
  machine is unavailable.
* Ara CLI 0.2.34 makes bare `ara device` self-healing for an enrolled Mac. If
  its managed LaunchAgent is stopped or missing, the command restarts it before
  reporting status without opening the native Device-proof boundary.
* Ara CLI 0.2.36 treats an expired or revoked interactive login as signed out.
  `ara status` still reports local MCP and Device health, `ara whoami` asks you
  to sign in, and `ara login` starts a fresh authorization instead of exposing
  the OAuth `invalid_grant` error. A login rotated by another Ara process is
  preserved.
* `ara update` now temporarily stops and restarts an active Device worker so it
  can actually activate a newer signed runtime immediately. It no longer says
  the installed version is current merely because the worker owns the runtime
  singleton. The update also safely adopts Ara's own older curl launcher so
  removed `tui` and `open` aliases cannot remain available through a stale
  `~/.local/bin/ara`; package-manager and unrelated launchers remain untouched.
* Browser diagnostics now renew their bounded event budget when a long-lived
  Ara tab changes routes, so later device and repository routing decisions stay
  visible in operational telemetry with the selected repository and signal.
* Generated `ara/agent/*` branch names stay readable in streamed and completed
  results after a Device-to-cloud or cross-repository continuation. Secret-like
  unknown tokens remain redacted; only the platform-owned branch identifier is
  preserved, including when the run and its installed MCP tools each apply a
  separate secret-redaction layer.
* Asking a session to connect to one of your machines now moves the session onto
  that machine and root. Previously the request was recorded but the session
  stayed pointed at the cloud, so the work queued for your computer could never
  be picked up: the Ara Device worker polled, was never offered the operation,
  and the session eventually failed waiting for hands to become ready.
* Disconnecting returns the session to your organization's cloud workspace, so
  you can hand work back and forth between your computer and the cloud within a
  single session.
* A connect request that names a machine which is offline, on an unsupported
  protocol version, or without an active granted root is refused and leaves the
  session on the cloud, rather than stranding it against hands that cannot
  arrive.

## August 10, 2026: Sessions stay in Ara Cloud

* The experimental terminal session command has been removed. Sessions and
  chat stay in Ara Cloud while the CLI focuses on login, updates, MCP, Device,
  and machine-wide status.
* `ara device` is idempotent and now reports its organization and last real
  task use when it is already configured.
* Ara CLI 0.2.32 keeps that repeated `ara device` status read outside the
  native signing boundary, so it works consistently from both the installed
  release and a source checkout without re-enrolling the computer.

## August 7, 2026 — Workspace reuse behind a Git proxy

* The Ara Device worker now reuses an existing run workspace on machines whose
  Git configuration rewrites remote URLs, via `url.<base>.insteadOf` (common
  with corporate Git proxies and with ssh-instead-of-https rules). The reuse
  check previously read the rewritten URL back and compared it against the
  original clone URL. Those never matched, so the worker treated a perfectly
  good checkout as foreign and re-cloned the repository on every run.

## August 7, 2026 — Notarized CLI and worker

* Ara CLI 0.2.31 ships an Apple-notarized command line and Ara Device worker.
  The signed broker and its Keychain library are now submitted to Apple's
  notary service during release, so macOS Gatekeeper clears them on first
  launch instead of warning that Apple could not verify the app is free of
  malware.
* The compiled worker no longer bundles the macOS `fsevents` native addon, so
  it no longer unpacks an unsigned helper library at runtime that triggered a
  second Gatekeeper warning. File watching falls back to the portable watcher.

## August 4, 2026 — Verified Device handoffs

* Ara Device and Ara Cloud now advertise and verify the same versioned worker
  entrypoint, protocol, and SHA-256 artifact before a session can claim the
  relay. A mismatched worker is fenced instead of accepting frames from a
  different build.

## August 3, 2026 — Clean-host worker packaging

* Execution-target status for a Device session now reads as a slim bar in place
  of the composer, the same way an archived session does, instead of a large
  block above the transcript. While Ara retries the Mac or moves the session to
  Ara Cloud, the bar states what it is waiting for and input stays closed; the
  **Retry Mac** and **Continue in Ara Cloud** choices sit inline in that bar.
* The background worker's login item now identifies itself as Ara wherever
  Ara for Mac is installed, instead of surfacing the signing certificate's
  developer name in macOS background-activity notifications and Login Items.
* Ara CLI 0.2.29 binds the active managed-runtime identity into its LaunchAgent
  configuration. After an upgrade, the next bare `ara device` gracefully
  replaces an older resident worker; repeated invocations on the same version
  remain idempotent. It also lets a completed Device session report its final
  Hands lifecycle events before Ara closes the run, so clean teardown is
  recorded without recovery cancellation or stale operation frames.
* Ara CLI 0.2.30 advertises the exact Ara Hands worker artifact so the broker
  can fence stale Device installations before enqueueing work. Older Devices
  remain registered for existing capabilities while Hands waits for the signed
  upgrade instead of receiving an incompatible payload.
* Ara CLI 0.2.27 validates persistent REPL requests before execution on the
  signed Bun runtime, preserving multi-statement and explicit-return browser
  calls without risking duplicate evaluation.
* Ara CLI 0.2.26 embeds the browser runtime metadata used by Ara Device, so a
  newly installed worker no longer depends on files from the release builder.
* Production publication now waits for the signed Darwin arm64 package to run
  its version and Device lifecycle checks on a checkout-free Mac.
* Ara's local operation broker now admits the long-lived Hands connection used
  by Device sessions, so a selected Mac can receive the session instead of
  stopping before the operation reaches its worker.
* Device checkpoints use leader-consistent object writes and reads, with a
  bounded transport retry, so a Mac and Ara Cloud can verify the same durable
  workspace even when they run in different regions.
* Ara persists verified Device checkpoint metadata under explicit database
  types before allowing the Mac turn to continue.
* Repository-bound Device sessions stay on the selected Mac when a full-tree
  checkpoint exceeds the 100 MiB safety cap. Ara durably marks cloud
  continuation unavailable and rejects stale checkpoint handoff instead of
  misreporting the Mac as unreachable or restoring older work.
* If a session restarts before a Mac binds, recovery fences the old Device
  writer, confirms the relay name is absent, then waits for the recreated cloud
  worker before starting relay services. If the old one-slot worker is still
  draining, Ara retries only that same Mac after complete cleanup; it never
  silently switches targets.
* Display prewarm skips Device relay workers because the real browser and
  desktop live on the enrolled Mac.

## August 2, 2026 — Managed native worker

* Run `ara login`, then bare `ara device`, to install or repair this Mac as a
  full-access background Ara Device. Repeating `ara device` is idempotent.
* The signed worker updates its managed runtime, health-checks the active
  release, and rolls back a failed activation.
* Ara Device stays an execution target for an Ara session; conversation and
  session history remain in Ara web.
* Ara CLI handles sign-in and local setup, MCP connects coding agents to Ara's
  typed tools, and Ara Device runs approved file and shell operations on the
  selected computer.
* To connect a Mac, open **Workspace → Devices**, choose **Copy Ara CLI setup**
  on the **Add a Mac** card, and complete the browser approval.