afire

The command-line client for Afire. 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

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:

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.

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):

## 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.