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.