See how the CLI runs commands on your computer, which tools it uses or installs with your OK, how Docker is handled, and what ysra doctor checks.

On this page

Commands are the programs Ysra runs on your computer during a change: tests, builds, your own tools. This page explains how they are contained, which of your tools Ysra uses, what happens when a tool is missing or Docker is needed, and how ysra doctor shows where the computer stands. On Windows the rules differ; see Windows.

The rule#

Commands run contained to the folder, with the network closed, unless you allow more. Installing, starting or signing in to anything is never done without your OK, and auto mode never answers those questions for you.

How Ysra runs commands#

On macOS and Linux each command runs in a contained space on the computer.

Contained command
Writes Only the folder you opened, a temporary folder, and package caches
Network Off by default. Installing dependencies opens the package registries (npm, PyPI, crates.io, the Go proxy). A tool you’ve allowed opens only that tool’s own sites
Left behind Nothing: Ysra’s bookkeeping never leaves stray files in the folder
Never read .env files, private keys, ~/.ssh, ~/.gnupg, hosting-provider credential folders, browser profiles, keychains
The computer can’t contain commands No command runs. Ysra says so and keeps reading and editing files. ysra doctor shows why

Keep more files from Ysra#

Add patterns, one per line, to .ysra/deny in the folder:

secrets/**
*.tfstate
config/production.yml

Ysra can’t read, search or change anything that matches, and can’t edit this file either.

Your own tools#

When a folder opens, Ysra notes which tools are installed: git, node, pnpm, python, go, docker, gh, and the command-line tools of common hosting services such as netlify and fly. It sees names and versions, never account names. So you can say “deploy this with my Netlify CLI” or “open a pull request with gh”.

Runs without asking Asks first, every time, auto mode included
Looking: netlify status, gh pr view, npm view Anything with an effect outside the computer: deploy, publish, create a release or pull request, set remote environment values

Ysra uses the tool’s existing sign-in. It never signs in for you.

When a tool is missing#

YSRA YOUR COMPUTER A step needs a tool missing, stopped, or not signed in Pause and propose one step showing exactly what would run You decide Go ahead, or Not now It runs on your computer your package manager, or a verified download Ysra checks the tool works The task continues from where it paused 1 2 proposal 3 your OK 4 5
A missing tool pauses the task; only the step you approve runs, on your computer.
Situation What Ysra does, with your OK
Node.js, Python or Git missing Pauses and asks (“I need Node.js to run your tests. Want me to install it?” Install · Not now). Installs the official build, checksum verified, into ~/.ysra/tools: nothing system-wide, nothing in your shell changes
Another tool not installed Installs with your package manager (Homebrew, winget, Scoop), or downloads the official build and verifies its checksum
Installed but not running (for example Docker) Starts it
Not signed in Nothing. Ysra shows the steps; signing in is yours to do
ysra runs as root in a container May also install with apt-get, apk, dnf or yum

Tools Ysra installed can be removed in the desktop app under Settings → General → Installed tools, or by deleting ~/.ysra/tools.

Fixed limits, whatever Ysra is asked:

  • no sudo;
  • no installers that need your password (.pkg, .dmg, .exe, .msi): Ysra gives the link and waits;
  • no removing or uninstalling anything;
  • only what the prompt shows runs;
  • auto mode never answers this question.

Afterwards Ysra checks the tool really works, then continues. Ask “how do I do it?” while it waits and it shows the steps to do it yourself.

A prompt asking before installing a missing tool

Asking before installing a missing tool, showing exactly what runs

When a command needs Docker#

Docker can reach well beyond one folder, so it has its own question: “Let my commands use Docker in this session?” Allow for this session · Not now.

Rule Value
Asked Once per thread, the first time a command needs Docker
Lasts That thread only
Auto mode Never answers it
While allowed /status shows Docker: allowed for this session
“Not now” Ysra carries on without Docker where it can; say “continue” to be asked again

ysra doctor#

ysra doctor

One line per check: ✓ fine, ✗ needs fixing, · information.

✓ ysra 1.20.0 (build …) (the latest)
· machine: macos arm64; package managers: brew
· hardware: 0 cameras, GPU: none
✓ commands: a test command ran safely contained
✓ Git: 2.50.1 (Apple Git-155)
✓ API: https://… (reachable; the default)
✓ signed in as you@example.com (from the Keychain)
· not signed in as a device (`ysra login --device`, on a server or edge device)
Line What it checks
ysra The version, and whether a newer one is available
machine The system, and the package managers Ysra may use with your OK
hardware Cameras and GPU
commands A test command really ran contained, or what’s missing
Git Git is installed
API Ysra can be reached from this computer
Sign-in The sign-in on this computer and where it was found (the Keychain, the system keyring, an owner-only file, or on Windows a file only your account can decrypt), and a device’s sign-in
A line like Means What to do
· ysra 1.8.0 (build …); 1.20.0 is out (`ysra update`) A newer CLI exists ysra update
✗ API: https://… can't be reached: the connection was refused No connection; the reason is named (DNS, TLS, a timeout, refused), with a hint if a proxy is set Check the network, VPN or proxy
✗ your sign-in expired (`ysra login`) Signed out ysra login
✗ this device was removed from your account (`ysra login --device` to add it again) The device was removed ysra login --device
✓ signed in as device edge-01 (observe mode) A device sign-in —

ysra doctor exits 1 when commands can’t run, Ysra can’t be reached, or a device’s sign-in has failed, so a script can test it.

If it doesn’t work#

Symptom What to do
Commands never run; Ysra only edits files The commands line in ysra doctor says what is missing
A test needs the network and fails The network is closed in commands; ask Ysra to allow the tool, or run it yourself
Ysra waits on an installer It needs your password; run the installer from the link it gave
Docker commands fail after “Not now” Say “continue” and allow Docker for the session
YsraDocs