Look up every ysra command, option, environment variable, slash command and key, for CLI {{ version.cli }}.

On this page

This page lists every ysra command and option, every slash command typed in the chat, the keys, and the files Ysra keeps on the computer, for CLI 1.20.0. Look a command up here; for how a folder session goes, see Work in a folder, and for scripts, see Run Ysra from a script.

ysra --help (or ysra help) lists the commands, and ysra <command> --help (or ysra help <command>) gives one command’s options with examples.

Commands#

Work#

Command What it does Options
ysra Open the chat in this folder’s last thread, printed into the terminal itself. The folder it starts in is what Ysra works on --continue / -c (the same, said explicitly) · --resume / -r (pick one of this folder’s threads first, as /sessions does) · --resume <thread> (open that thread, by its id or the start of it) · --fullscreen (pinned message box; or /settings → Screen) · --inline (always in the terminal, whatever the setting) · --demo (a scripted session: nothing is sent, no account needed)
ysra resume [thread] The same as ysra --resume [thread] —
ysra exec "<task>" Run one task to the end with nobody at the keyboard. ysra -p "<task>" is the same. What is piped in goes with the task See Options for ysra exec
ysra ask "<question>" Ask Ysra a question; files the answer makes are saved in the current folder See Ask from the terminal
ysra mayz [folder] Have Mayz review a folder as it is. Never changes the folder See Review a project
ysra help [command] Every command, or one command’s options with examples —

Options for ysra exec#

Option What it does
--output-format text|json|stream-json text (default): Ysra’s answer. json: one result object at the end. stream-json: one JSON event per line, each with its time (ts), ending with the result. See What is printed
--trace <file.jsonl> Also write every raw event the CLI receives to this file, one JSON object per line, and keep the local transcript. Where available, Ysra’s record of the run is saved next to it as <file>.server.json
--trace-max-mb <n> The most the server’s record may be, in MB. Default 512
--approval ask|auto|read-only ask (default): stop at the first decision and report it. auto: go ahead with the work in the folder; decline what reaches outside it. Only in a container, or with --yes-i-am-sandboxed. read-only: only look; nothing in the folder is changed, installed or deleted
--yes-i-am-sandboxed This machine is disposable (a VM, a CI runner): allow --approval auto here and let it run the project’s code
--allow <kinds> With --approval auto only: also go ahead with these, a comma list of commit, push, deliver (a draft pull request), deploy, publish and undo. Default: none
--approve-plan Accept Ysra’s plan instead of stopping at it in ask mode
-C <dir>, --cd <dir> Work in this folder, with Git or without. Nothing is set up in it
--allow-home Allow the home folder or the top of the disk as the folder, where the service offers it. Only plain reading commands run there unattended
--allow-computer-writes <path>,… With --allow-home: let plain file creates and edits inside these paths run with --approval auto. Edits keep a backup; never deletes, moves, installs or permission changes
--mode spark|forge|summit Work in this Code mode. --model and --effort win over it
--model <name> Use this model, by the name or id /model shows
--effort quick|balanced|thorough How hard Ysra thinks (low, medium, high work too). Default: your setting
--review mayz When the work is done, Mayz reviews it in the same thread; while it needs work, Ysra fixes the findings and Mayz reviews again
--review-rounds <n> The most Mayz reviews in all, 1 to 5. Default 2
--max-credits <n> Stop before this thread uses more than n credits, 1 to 50,000
--timeout <dur> End the run after this long (90s, 15m, 2h, 1h30m; a plain number is seconds). The work is kept
--max-turns <n> End the run once the thread has made n model calls in it. The work is kept
--continue Go on in this folder’s last thread
--resume <thread> Go on in this thread
-h, --help The command’s help

Exit codes 0 to 12 are listed in Run Ysra from a script.

Ask from the terminal#

$ ysra ask --file q3.xlsx "summarise revenue by region as a new spreadsheet"
Option What it does
--file <path>, -f Attach a file: PDF, Word (.docx), Excel (.xlsx), CSV, Markdown, text or an image. Repeat for more, up to 20
--research deep Research the question in depth. It takes longer
--expert <name> Ask one of your colleagues, named as in the web app
--json Print the answer, its sources and the saved files as JSON
-h, --help The command’s help

ysra ask answers on Auto, so Ysra picks Quick or Thorough for each question, or uses the colleague’s own speed with --expert; --research deep is always Thorough. See Auto, Quick or Thorough.

The answer is printed with its sources. Each file in the answer is saved in the current folder with one Saved <name> line. An existing file is never overwritten: a second report.xlsx is saved as report (2).xlsx.

Exit code Means
0 Answered
1 Failed
2 An action Ysra proposed waits for your approval in the web app
3 Out of credits, or the account is paused

Review a project#

$ ysra mayz ~/code/shop --focus security
$ ysra mayz . "check the checkout flow and the admin pages"

Mayz runs the project and its tests in its own copy and writes a report: findings by severity, each with its evidence, what it couldn’t check, and what it cost. It never changes the folder. Say “fix these” afterwards to fix them in Code. Offered where the service offers Mayz.

Option What it does
--focus all|security|quality|design What to look at. Default all
"<what to look at>" A brief in quotes, after the folder
-p, --print Run to the end with nobody at the keyboard and print the report. The options of ysra exec also apply (--approval, --max-credits…)
--output-format text|json|stream-json As for ysra exec. json gives the result with the report in it
Exit code (--print) Means
0 Ready
1 Needs work
2 Unsafe
3 Not finished, or no report. A review that didn’t finish (for example the credits ran out) is never reported as ready

Account#

Command What it does Options
ysra login Sign in from the browser. Over SSH, it prints a code to enter in the web app --no-browser (a code, even with a browser here) · --password (email and password) · --token (keep a token you already have; asked for, hidden) · --device (sign this computer in as a device, approved in the Ysra app, for ysra serve and ysra machines)
ysra logout End this computer’s sign-in. A device’s own sign-in stays; ysra uninstall removes it —
ysra auth token Print a short-lived access token (good for at least 30 more minutes) from this computer’s sign-in. Exit 1 with the reason when signed out. See Sign in from a script —
ysra sessions Where the account is signed in —
ysra usage Credits left, the plan, and where the credits went. See Credits --json
ysra billing Open the web app’s Billing page and print its link. Nothing is paid for in the terminal. See Billing in each app plans · credits (open that part)

This computer#

Command What it does Options
ysra serve --folder <path> Keep a folder on this device available to Ysra. Sign the computer in first with ysra login --device --folder (repeat for more) · --install-service (Linux: keep it running as a systemd user service)
ysra machines add Add a machine; asks for the details —
ysra machines import <file.csv> On a gateway: add many machines at once. Asks once to confirm their host keys. Addresses stay on this computer --yes (confirm the host keys without asking, once checked)
ysra machines list Show the machines (ls works too) —
ysra machines mode <name> observe|change Let Ysra only look, or also change things (each change still asks) —
ysra machines production <name> on|off Mark a machine as production: destructive steps then need its name typed —
ysra machines reads <name> allowed|ask Let Ysra look at a machine nobody watches without asking. Changes still ask —
ysra machines rm <name> Remove a machine. Its log stays —
ysra approvers add <public key> --name "<name>" On a gateway: trust an approver. Compare the fingerprint with their app. See Approvals and automatic runs --yes (trust without asking)
ysra approvers list Who is trusted, whether approved runs are on, and the ceiling —
ysra approvers rm <fingerprint or name> Stop trusting one —
ysra approvers runs on|off Carry out approved runs at all. Off by default —
ysra approvers ceiling <kinds> The kinds of action that may ever run from an approval: a comma list of read, service, config, packages, network, containers, delete, power, users, access, shell —
ysra skills push Upload your skills from ~/.ysra/skills and other coding agents' skill folders, so work in Ysra’s cloud has them. A skill already there is skipped, a changed one updated; with the same name in both folders, ~/.ysra wins. See Skills --dry-run (list them, send nothing)
ysra contain Windows, alpha: paused for now, so commands ask before each one. status, off and uninstall still work. See Windows status · off · uninstall
ysra wsl Windows: run commands contained inside WSL off (back to asking before each command)
ysra doctor What this computer offers Ysra: how commands are contained, hardware, package managers, the sign-in. Exits 1 when something needs fixing. See ysra doctor —
ysra update Replace ysra with the latest release, checked against the release’s checksum first —
ysra uninstall Remove Ysra from this computer; asks before deleting ~/.ysra. See Uninstall --purge (delete it without asking) · --keep-data (keep it without asking)
ysra --version Print the version —

ysra target … is the older name for ysra machines … and still works.

Environment#

Variable Default What it does
FORGE_API_TOKEN — Sign in without a browser, for CI, scripts and containers. ysra auth token prints one. See Sign in from a script
FORGE_WORKSPACE_ID Your first workspace The workspace
YSRA_HOME ~/.ysra Where Ysra keeps its files
YSRA_NO_UPDATE_CHECK unset 1 turns off the once-a-day check for a newer version
YSRA_ALLOW_ROOT unset 1 lets ysra run as root or an elevated Administrator, for a container made for the run

An organisation’s policy file can turn off --allow-home, --allow-computer-writes, --approval auto, --yes-i-am-sandboxed and --allow words; nothing on the command line turns them back on. It lives at /etc/ysra/policy.json (Linux), /Library/Application Support/Ysra/policy.json (macOS) or %ProgramData%\Ysra\policy.json (Windows).

Slash commands#

Type these in the message box. /help lists the essential ones and /help all lists every one; Tab completes.

Conversations#

Command What it does
/new [request|@file.md] Start a separate conversation in this folder
/sessions [search] Resume a recent conversation for this folder
/status Where things stand right now
/cancel Stop what Ysra is doing and keep the conversation
/quit Exit. /exit and /q work too

Seeing what Ysra did#

Command What it does
/plan The current plan and to-dos
/spec The latest specification Ysra wrote
/approve [version] Approve the specification and start building it
/activity The history of what Ysra did
/context What Ysra is working from: requirements, files, memory
/diff Ysra’s latest changes, and everything a commit would include
/eval The quality scorecard for the latest work
/usage Credits left, the plan and its refill date, the last 30 days by kind of work, and recent work. /cost is the older name
/billing Open the web app’s Billing page; /billing plans or /billing credits opens that part. Nothing is paid in the terminal

Reviewing with Mayz#

Command What it does
/mayz [focus] Mayz reviews this thread’s finished work: ready, needs work or unsafe. /review is the same
/mayz fix [F1 F2] Fix the report’s findings (“fix these”), or only the ones named
/mayz again Mayz reviews again, afresh (“review again”)

Machines, in a thread on a gateway#

Command What it does
/machines The machines and their last reading in this session
/runs [n] Runs on the machines in this session. /runs 2 opens one, machine by machine
/approvals Approvals for unattended runs. Withdraw one here; signing is in the desktop app

Keeping or reverting work#

Command What it does
/commit [--branch name] [--new] [msg] Commit Ysra’s changes on a branch, new or existing. Never pushes
/push [--branch name] [--new] [msg] Commit Ysra’s changes and push them. Asks before pushing
/deliver [msg] Commit, push a branch and open a draft pull request. Asks first
/undo Put back exactly what Ysra changed. Your own changes stay
/delete Delete this thread from Ysra, after you say yes. Your files in the folder stay
/checkpoints List earlier points to return to
/rewind SEQ Return to an earlier point. Checks made after it no longer count

Details: Commit, push and undo.

Running your app#

Command What it does
/preview Start the app to open it in the browser
/stop-preview Stop it

Settings#

Command What it does
/access [auto|ask|read-only] Set this thread’s access: Auto, Asks first or Read only. Shift+Tab under the input does the same. See Access modes
/auto on|off Switch Auto on or off for this thread; Auto still asks before risky things. On Windows without WSL it also lets commands run without asking, for this session only: see Windows
/computer look|changes on|off Let Ysra look at this computer when started in the home folder or at the top of the disk, and change things there (each change asks). With look on, a folder's thread can also look at the rest of the computer, read only. Listed only where the service offers it
/settings Choose model, reasoning, quality, compute, access and screen. Applies from your next message in this thread
/mode [spark|forge|summit] Choose a Code mode: a model and an effort together. Kept for new threads
/model Choose the model (type to search). Kept for new threads
/effort [quick|balanced|thorough] Choose how hard Ysra thinks. Kept for new threads
/login Sign in, or switch account
/ws Switch workspace
/repo owner/name, /repos, /local Pick a hosted repository, list them, or go back to the folder ysra started in
/help The essential commands
/help all Every command

/help all also lists older task and Project-mode commands (/tasks, /task, /run, /retry, /watch, /detach, /project new, /projects and others). They are kept for older threads and not described here.

Keys#

Keys Action
Enter Send
Tab Complete a slash command
Shift+Tab Cycle the thread’s access: Auto, Asks first, Read only
Mouse wheel, or the terminal’s scrollback Scroll
Ctrl+O Show the latest step in full
Esc Stop waiting
Ctrl+C Interrupt; twice to quit
↑ / ↓ with an empty message box, then Enter In full screen, select a step and open it

/settings → Screen has three choices; ysra --fullscreen picks the second for one session.

Screen Means
In the terminal “the terminal scrolls, selects and copies”
Full screen “pinned input; PgUp/PgDn scroll, ↑↓ and ⏎ open rows”
Full screen, mouse clicks “the wheel scrolls and clicks open rows; the terminal can’t select text”

Files Ysra keeps#

Everything lives in ~/.ysra (or YSRA_HOME), readable only by you. Nothing is written inside a folder except the changes you asked for.

Path What
~/.ysra/targets.json The gateway’s machine list. Only on this computer
~/.ysra/targets/<name>/log.jsonl What ran on each machine, and who approved it
~/.ysra/tools/ Tools Ysra installed with your OK
~/.ysra/computer-backups/<run>/ Copies kept before --allow-computer-writes edited a file
<folder>/.ysra/deny Yours to write: extra files Ysra must never read. See Keep more files from Ysra
<folder>/.ysraignore Yours to write: files left out of Ysra’s record of the folder, in .gitignore syntax. .gitignore is honoured too
YsraDocs