---
title: "Work in a folder"
description: "Sign in, open a folder, ask a question or describe a change, and follow what I do."
---

In the terminal you talk to me in plain language. I work on the folder you
started me in: I read it, change it when you ask, run its checks, and show you
everything I did.

> Diagram: I plan and review; the reading, editing and running happen in your folder, and the change stays there until you decide.

## Sign in

```bash
ysra login
```

Enter your Ysra email and password. Your sign-in is kept in the macOS Keychain,
or in a file only you can read on Linux. You can also just run `ysra`: if
you're signed out, I ask there.

## Open a folder

```bash
cd ~/code/billing-service
ysra
```

The folder you start me in is the folder I work on. Nothing else.

- The first time, I ask whether you trust the folder. I remember the answer.
- A folder without Git works too.
- Next time you run `ysra` in the same folder and branch, I pick up the same
  conversation.

![Ysra started in a folder in the terminal](../assets/screens/cli/open-folder.webp){ width="1698" height="606" }
/// caption
Started in a folder
///

## Ask, or ask for a change

Type what you want. You don't pick a mode.

```text
› explain how refunds are calculated
› fix the failing invoice tests and add support for partial refunds
```

- A **question** gets an answer with the files I read to reach it.
- A **change** gets done in your folder: I edit, run your checks, review the
  result, and report.
- While I'm working, anything you type is either a question I answer or a
  steer I pick up at the next safe point.

To hand me a written brief, attach it with `@`:

```text
› @PLAN.md
```

Checklist items and anything under "Acceptance criteria" or "Done when" become
the criteria I check the work against.

## The working timeline

Everything I do appears as I do it:

```text
 › fix the failing invoice tests and add support for partial refunds

 ● Read AGENTS.md · src/billing/**
 ● Edit src/billing/refunds.ts  +6 −1
 ● Run pnpm test  exit 1
   ⎿ ✗ tests/refunds.partial.test.ts > exceeds balance
 ● Repair clamp to remaining balance; round to cents  +1 −0
 ● Run pnpm test

 ✓ Ready  1:42
   checks     ✓ pnpm test   ✓ pnpm typecheck
   acceptance ✓ a partial refund cannot exceed the remaining balance
```

| Mark | Meaning |
|---|---|
| `›` | What you typed |
| `●` | Something I did: read, edit, run, review |
| `⎿` | Evidence for the line above: output, a diff, a failing test |

![The working timeline in the terminal during a change](../assets/screens/cli/timeline.webp){ width="1698" height="1450" }
/// caption
The working timeline during a change
///

**Moving around**

| Keys | Action |
|---|---|
| Mouse wheel, PgUp / PgDn, Shift+↑ / ↓ | Scroll |
| Esc | Back to live |
| ↑ / ↓ with an empty message box, then Enter | Select a step and open it (full diff or output) |
| Tab | Complete a slash command |

Prefer your terminal's own scrollback, search and copy? Start with
`ysra --inline`.

## When I ask for your OK

I stop and ask before:

- **deleting** a file I didn't create in this task;
- **anything that reaches outside your folder or computer**: a deploy, a
  publish, a push, creating something on a remote service. I show the exact
  command and where it runs: *"I'm about to run `netlify deploy --prod` in
  this folder with your Netlify account. OK?"*
- **a Git change you didn't ask for**;
- **installing or starting something** on your machine
  (see [Tools, setup and Docker](machine-setup.md));
- **anything on a [device](../devices/overview.md) or [target](../targets/overview.md)**
  that changes it.

Answer in the prompt that appears. "No", or no answer, means I don't do it.

![An approval prompt before a deploy](../assets/screens/cli/approval.webp){ width="1520" height="606" }
/// caption
Asking before a deploy
///

## Auto mode

```text
/auto on
/auto off
```

With auto mode **on**, I go ahead inside your folder without asking: starting
work, editing files, running commands there.

Auto mode never covers:

- deleting anything;
- anything outside the folder or your computer (deploying, pushing,
  publishing);
- Git changes you didn't ask for;
- installing or starting tools, and the Docker OK;
- any change on a device or target.

With auto mode **off**, I ask before starting work that costs money.

## Stopping and pausing

- `/cancel` stops what I'm doing and keeps the conversation.
- If you close Ysra while I'm working, I pause: *"I paused because Ysra was
  closed on this folder — open it to continue."* Run `ysra` there again and I
  carry on from the same place.

## Your balance

There are no per-task budgets to set. Work draws from your account balance.
The only time I bring money up is when it runs low: *"Your balance is low — top
up to continue."* `/cost` shows what this conversation has used.

## Next

<div class="cards" markdown>

- [**Commit, push, undo**](commit-push-undo.md)

    Keep my work, or put everything back.

- [**Tools, setup and Docker**](machine-setup.md)

    What I may install or start, and how I ask.

- [**Command reference**](commands.md)

    Every command and slash command.

</div>