# The CLI's log

The CLI keeps its own log at `<config>/logs/devmachine.log`.
`devmachine logs path` prints where that is. When `setup`, `sync` or
another command that changes a machine fails, the last line it prints
says where too:

```
error: the bootstrap stopped at "install ansible"
log: /home/alice/.config/devmachine/logs/devmachine.log
```

That file is what to send when you ask for help.

## What goes in it

A command that changes a machine is logged whole: `setup`, `machines
add`, `sync`, `update`, `doctor`, `packages add` and `remove`, `run`,
`login`, `credentials push`, and the others that add, remove or start
something. Each run writes a start line, every line the command printed
(Ansible's output included), and an end line:

```
2026-10-20T12:00:00.000Z [4242] start  devmachine 0.16.0 darwin/arm64: sync --machine main
2026-10-20T12:00:03.120Z [4242] out    TASK [base : install packages] on main (203.0.113.10)
2026-10-20T12:00:41.900Z [4242] err    fatal: [main]: FAILED! => {"msg": "no package matching 'foo'"}
2026-10-20T12:00:42.010Z [4242] end    failed (exit 1) after 42.01s: sync on main failed
```

The number in brackets is the process. The macOS app can run several
commands at once, and their lines mix in the file; the number tells them
apart.

Every other command only writes a line when it fails, and never its
output. The app runs `sessions`, `stats`, `machines list` and `run
--package devmachine-app` every few seconds. Their output, logged whole,
would fill 5 MB in a day and push out the `setup` you wanted to read.
`run --no-log` counts as one of these reads.

A command that only reads does not print the `log:` line either. The app
reads what those commands print, and a line it did not expect is a line
it has to skip.

## What is taken out

Before a line reaches the file, the CLI replaces with `***`:

- the value of any `NAME=value` or `"name": "value"` whose name holds
  `token`, `secret`, `password`, `passwd`, `api_key`, `private_key` or
  `auth`
- a line shaped like a `.env` file, `NAME=value` in capitals
- `Authorization:` headers and `Bearer` tokens
- GitHub tokens (`ghp_`, `gho_`, `github_pat_`), keys starting with
  `sk-`, and Tailscale auth keys (`tskey-`)
- the password in an address like `https://alice:…@example.com`
- a private key, from its `-----BEGIN … PRIVATE KEY-----` line to its
  end
- on the command line, the value of a flag like `--token`, `--password`
  or `--value`, and the value given to `secrets set`

A password typed at a prompt or piped with `--password-stdin` never
reaches the log at all: the log copies what the CLI prints, not what it
reads.

What stays is what makes the log useful: addresses, host names, machine,
workspace and user names, and the commands that ran. Read the file
before you send it if any of those are private to you.

## What it looks like

The file holds plain text. Colours, cursor moves and window titles are
taken out, and a line that redraws itself, like a download's progress
bar, keeps only the state it ended in: `Downloading 100%`, not every
step on the way.

## Why the programs it runs still see your terminal

To copy what a command prints, the CLI has to read it on its way to
your terminal. A program like Homebrew, or a command `run` starts on a
`self: true` machine, would then find itself writing into the CLI
instead of a terminal, and print plain: no colours, no progress bars,
the wrong width. So when your output is a terminal, the CLI gives such
a program a terminal of its own, the same size as yours, and passes
everything it prints to yours unchanged while the log keeps a plain
copy. What you see is what you saw before the log existed.

When the output is not a terminal, as in the macOS app, a pipe or a
file, the program gets a pipe and prints plain, as it always did.
Questions the CLI asks you are not affected either way: the log copies
what the CLI prints, never what you type.

## Size

When the file passes 5 MB, it becomes `devmachine.log.1`, the old `.1`
becomes `.2`, `.2` becomes `.3`, and the old `.3` is deleted. So the
logs never take more than about 20 MB.

## Why it never fails a command

Writing the log can go wrong: a full disk, a folder you made read-only.
The CLI then carries on without it, and says nothing. A log that can
stop `sync` is a log somebody turns off the first time it does.

## Why it is never committed

`logs/` holds a `.gitignore` of its own that ignores everything in it.
A configuration folder that became a repository before the log existed
has a `.gitignore` without `logs/`, and its next commit would have
picked the log up. With its own `.gitignore`, the folder stays out
whatever the top one says. `devmachine setup git` also adds `logs/` to
the top one, and refuses a commit that tracks it, the same as
`history.log`. See
[versioning your configuration](/how-it-works/versioning-your-configuration/).