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 |