Metadata-Version: 2.4
Name: afire-ai
Version: 1.3.1
Summary: Command-line client for Afire: run commands, move files and open shells on your devices.
Project-URL: Homepage, https://afire.ai
Keywords: afire,remote,devices,fleet,cli
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: websocket-client>=1.0

# afire

The command-line client for [Afire](https://afire.ai). Run a command on any of
your devices and get its output and exit code back, move files, and open a
shell, from your own terminal or from a coding agent.

## Install

```sh
pip install afire-ai
afire --help
```

Python 3.9 or newer. The only dependency is `websocket-client`.

The same program is also a single file: `afire.py`, downloadable from any
device page. `python3 afire.py run ...` and `afire run ...` behave the same.

## Make a token

1. Open **Settings → API tokens** (`/settings#tokens`).
2. Give the token a label and press **generate**. Copy it: it is shown once.
3. Put it in your environment:

```sh
export AFIRE_TOKEN="paste-the-token-here"
```

The default scopes cover everything below. `run`, `push`, `pull` and
`screenshot` need the **control** scope; `ssh` needs **ssh**; `ls` needs
**read**.

**Limit a token to some devices.** Under **scopes…**, set **devices** to
**only these** and tick the devices. That token can run commands, move files
and open a terminal on those devices and no others, and it cannot start agent
chats. Use one of these for scripts and coding agents.

`AFIRE_URL` points the client at a different server. Leave it unset to use the
default.

## The five commands most people use

Devices can be named by id or by name. Put names with spaces in quotes.

```sh
afire ls                                   # your devices and whether they are online
afire run "my laptop" "df -h"              # run one command, print its output
afire ssh "my laptop"                      # interactive shell
afire push "my laptop" ./build.zip /tmp/   # copy a file to a device
afire pull "my laptop" /var/log/app.log ./ # copy a file from a device
```

`run` prints the command's own stdout and stderr and exits with the command's
own exit code. It runs in the device's afire workspace (`~/afire`) unless you
pass `--cwd`. Use full paths for `push` and `pull`: an unquoted `~` is
expanded by your own shell before `afire` sees it. On a Windows device the
shell is `cmd.exe`; pass `--shell powershell` for PowerShell. Long scripts read from a file with
`--file script.sh` (or `--file -` for stdin), so no local shell can change
them on the way.

Exit code **75** means the command reached the device but the reply was lost.
It may have run. Check its effect before running it again.

Run `afire --help` for everything else: `cp` between two devices, `forward`
a port, `screenshot`, `input` (mouse and keyboard), `audio` and more.

## Run commands on your device from any coding agent

Make a token limited to the device, set `AFIRE_TOKEN` in the environment the
agent runs in, and add this to the agent's instructions file (`CLAUDE.md`,
`AGENTS.md`, `.cursorrules` or similar):

```markdown
## Running commands on my build box

Use the `afire` CLI to run commands on the device named "build-box".

    afire run build-box "cd ~/app && git pull && make test"

- Output is the command's own stdout and stderr; the exit code is the command's own.
- For anything with quotes, pipes or several lines, write it to a file and use
  `afire run build-box --file script.sh`.
- Copy files with `afire push build-box ./dist/app.tar.gz /srv/app/` and
  `afire pull build-box /srv/app/logs/test.log ./`.
- A request held open longer than about a minute can be dropped by the network.
  For long jobs, start them in the background on the device and check on them
  with a second `afire run`.
- Exit code 75: the command reached the device but the reply was lost. Check
  its effect before running it again.
```

The agent then runs `afire run build-box "..."` like any other shell command
and reads the result.
