Every command

This page is generated. site/scripts/gen-commands.mjs runs aos commands --json --all against the source tree and writes this file every time the site is built, so it cannot describe a command the binary does not have, or miss one it does.

103 commands across 33 groups. 3 internal ones are marked hidden and not listed below.

needs a display marks a command that is refused with a reason on a machine with no screen. platforms appears only where a command does not exist everywhere; everything else runs on macOS, Windows and Linux.

The same data, machine-readable, comes from the binary you installed:

aos commands --json --all

adapters

`aos adapters example [--write]`

Print a starter adapter, ready to save and edit

aos adapters example
aos adapters example --write

`aos adapters list [--json]`

List the adapters this machine has loaded

aos adapters list

`aos adapters path`

Print the directory adapters are read from

aos adapters path

audio

`aos audio mute [on|off|toggle]`

Print or change the output mute state

aos audio mute toggle

`aos audio volume [<0-100>|+<n>|-<n>]`

Print the output volume, or set it

aos audio volume
aos audio volume 40
aos audio volume +5

battery

`aos battery percent`

Print the charge percentage as a bare number

aos battery percent    # 87

`aos battery present`

Exit 0 when a battery is present, 1 otherwise

aos battery present && echo has a battery

`aos battery status`

Print battery charge and charging state

aos battery status

capture

`aos capture screenshot [fullscreen|region|window] [--monitor=<n>] [--region=<x,y,w,h>] [--app=<name>] [--copy] [--out=<path>]`

Take a screenshot

needs a display · also: screenshot

aos screenshot
aos capture screenshot region --copy
aos capture screenshot --monitor=2
aos capture screenshot --app=Chrome --out=/tmp/term.png
aos capture screenshot --region=0,0,800,600

clipboard

`aos clipboard copy [text...]`

Copy stdin, or the given words, to the clipboard

echo hello | aos clipboard copy
aos clipboard copy "some text"

`aos clipboard paste`

Print the clipboard to stdout

aos clipboard paste > note.txt

completion

`aos completion <bash|zsh|fish>`

Print a shell completion script generated from the command tree

aos completion bash
aos completion zsh
aos completion fish

debug

`aos debug`

Print a diagnostic dump: platform, tools, plugin dirs

aos debug

`aos debug tools`

Report which helper tools are installed

aos debug tools

display

`aos display active`

Print the ID of the monitor the pointer is on

needs a display

aos capture screenshot --monitor=$(aos display active)

`aos display focused`

Print the ID of the monitor holding the frontmost window

needs a display

aos window move Chrome --monitor=$(aos display focused)

`aos display list`

List attached monitors with geometry and focus state

needs a display · also: monitors

aos display list

doctor

`aos doctor [--json]`

Diagnose this installation and say how to fix what is broken

aos doctor
aos doctor --json

exec

`aos exec capture <command> [args...]`

Run a command and print stdout, stderr, and exit code as JSON

aos exec capture git status
aos exec capture -- ls -la

`aos exec run <command> [args...]`

Run a command with its output streamed to this terminal

aos exec run git status

`aos exec shell <script>`

Run a command line through the platform shell

aos exec shell "git log --oneline | head -5"

file

`aos file append <path> [text...]`

Append stdin, or the given words, to a file

aos file append log.txt "done"

`aos file copy <source> <destination>`

Copy a file

aos file copy a.txt b.txt

`aos file delete <path> [--recursive]`

Delete a file, or a directory with –recursive

aos file delete /tmp/scratch --recursive

`aos file list [path] [--all] [--json]`

List a directory

aos file list
aos file list ~/Downloads --json

`aos file mkdir <path>`

Create a directory, including parents

aos file mkdir ~/.config/aos/layouts

`aos file move <source> <destination>`

Move or rename a path

aos file move old.txt new.txt

`aos file read <path> [--lines=<from>:<to>]`

Print a file, optionally a line range

aos file read go.mod
aos file read main.go --lines=10:40

`aos file stat <path> [--json]`

Print one path’s size, mode, and modified time

aos file stat go.mod --json

`aos file write <path> [text...]`

Write stdin, or the given words, to a file

aos file write notes.txt "first line"
cat in.txt | aos file write out.txt

font

`aos font dirs`

Print the directories fonts are read from

aos font dirs

`aos font list [filter]`

List installed font families

aos font list
aos font list mono

headless

`aos headless run <command> [args...]`

Run a command against the managed virtual display

aos headless run aos window list

`aos headless start [--display=:99] [--size=<WxH>] [--wm]`

Start a virtual display, so window and input commands work

platforms: linux

aos headless start
aos headless start --display=:101 --size=1920x1080 --wm

`aos headless status`

Report whether a display is available, and where it came from

aos headless status

`aos headless stop`

Stop the virtual display this machine started

platforms: linux

aos headless stop

key

`aos key press <combo> [--app=<name>|--title=<substring>]`

Press a key combination

needs a display

aos key press cmd+shift+s
aos key press enter --app=Chrome

`aos key type <text...> [--app=<name>|--title=<substring>]`

Type text, optionally into a named window

needs a display

aos key type "hello world"
aos key type "hello" --app=Chrome

launch

`aos launch <app> [args...] [--wait[=<ms>]]`

Launch an application, optionally waiting for its window

needs a display

aos launch "Visual Studio Code"
aos launch Chrome --wait

mouse

`aos mouse click [<x> <y>] [--button=left|right|middle] [--double] [--monitor=<n>]`

Click, optionally moving to a point first

needs a display

aos mouse click
aos mouse click 400 300 --double
aos mouse click --button=right

`aos mouse move <x> <y> [--monitor=<n>]`

Move the pointer

needs a display

aos mouse move 400 300
aos mouse move 400 300 --monitor=2

`aos mouse position`

Print the pointer position as x y

needs a display

aos mouse position     # 784 539

network

`aos network ip`

Print the local address of the active interface

aos network ip         # 192.168.1.20

`aos network status`

Print the active interface, address, and Wi-Fi network

aos network status

`aos network wifi`

Print the Wi-Fi network currently joined

aos network wifi

obs

`aos obs audit [--since=<duration>] [--source=<cli|mcp>] [--failed] [--json]`

Every command this machine was asked to run, oldest first

aos obs audit --since=24h
aos obs audit --source=mcp     # only what agents asked for
aos obs audit --failed

`aos obs export [--since=<duration>]`

Emit recorded spans as OTLP JSON, ready for a collector

aos obs export --since=1h > spans.json

`aos obs path`

Print where telemetry is written

aos obs path

`aos obs stats [--since=<duration>] [--source=<cli|mcp>] [--json]`

Summarise recorded work: calls, failures, and latency per route

aos obs stats
aos obs stats --since=24h --source=mcp

`aos obs summary [--since=<duration>] [--json]`

How much this machine is actually used, and by what

aos obs summary
aos obs summary --since=7d

`aos obs tail [--limit=<n>] [--since=<duration>]`

Print the most recent spans, newest last

aos obs tail --limit=20

open

`aos open <path-or-url>`

Open a file, folder, or URL with the system default handler

needs a display

aos open https://claude.ai
aos open .

permission

`aos permission check`

Report whether accessibility and screen capture are granted

needs a display

aos permission check

`aos permission request [accessibility|screen]`

Ask the OS for the permissions that are missing

needs a display

aos permission request
aos permission request screen

pkg

`aos pkg install <package...>`

Install packages

aos pkg install <package...>

`aos pkg list`

List installed packages

aos pkg list

`aos pkg manager`

Print which package manager this machine uses

aos pkg manager        # homebrew

`aos pkg refresh`

Refresh the package index

aos pkg refresh

`aos pkg remove <package...>`

Remove packages

aos pkg remove <package...>

`aos pkg search <term>`

Search for packages

aos pkg search <term>

`aos pkg upgrade`

Upgrade installed packages

aos pkg upgrade

power

`aos power status`

Print the current power source (ac or battery)

aos power status

process

`aos process find <name> [--json]`

Find processes whose name contains a substring

aos process find Chrome
aos process find node --json

`aos process kill <pid|name> [--force]`

Kill a process by pid, or by name when it is unambiguous

aos process kill 4821
aos process kill Calculator
aos process kill Calculator --force

`aos process list [--filter=<substring>] [--json]`

List running processes

aos process list
aos process list --filter=chrome
aos process list --json

remote

`aos remote share [--monitor=<n>] [--port=<n>] [--fps=<n>] [--key=<k>]`

Share this screen and its mouse/keyboard over the LAN until interrupted

needs a display

aos remote share
aos remote share --monitor=2 --fps=8

`aos remote url`

Print the URL of the share running on this machine

needs a display

aos remote url

serve

`aos serve mcp [--addr=<host:port>] [--token=<k>] [--groups=<a,b>] [--gui=on|off|auto] [--quiet]`

Serve every command as an MCP tool over streamable HTTP

aos serve mcp
aos serve mcp --addr=127.0.0.1:9000 --groups=window,capture,exec
aos serve mcp --gui=off   # screenless tools only

`aos serve tools [--groups=<a,b>]`

Print the MCP tool catalogue this machine would expose

aos serve tools --groups=window

service

`aos service create <name> [--autostart] [--now] -- <command> [args...]`

Install a command as a service

aos service create mcp --autostart --now -- aos serve mcp
aos service create nap -- /bin/sleep 60

`aos service list`

List the services aos manages

aos service list

`aos service remove <name>`

Stop a service and delete its definition

aos service remove mcp

`aos service start <name>`

Start an installed service

aos service start mcp

`aos service status <name>`

Report whether a service is running; exits non-zero when it is not

aos service status mcp

`aos service stop <name>`

Stop a running service

aos service stop mcp

skill

`aos skill install [--json]`

Install the bundled agent skill for every agent on this machine

aos skill install

`aos skill path`

Print where skill install would write

aos skill path

`aos skill show`

Print the bundled skill without installing it

aos skill show

`aos skill uninstall [--json]`

Remove the installed agent skill

aos skill uninstall

subtitle

`aos subtitle show <text...> [--seconds=<n>] [--position=bottom|top|center] [--size=<px>] [--wait]`

Show large text over everything for a few seconds

needs a display

aos subtitle show "installing dependencies"
aos subtitle show "running the migration" --seconds=30 --position=top
aos subtitle show "step 1 of 3" --seconds=4 --wait
# prints which backend was used: an overlay, or a notification it fell back to

`aos subtitle test`

Show a short sample, to check subtitles work on this machine

needs a display

aos subtitle test

system

`aos system info`

Print OS, host, and hardware facts

aos system info

`aos system lock`

Lock the screen

needs a display · also: lock

aos system lock

`aos system logout`

Log the current user out

needs a display

aos system logout

`aos system restart`

Restart the machine

aos system restart

`aos system shutdown`

Power the machine off

aos system shutdown

`aos system sleep`

Put the machine to sleep

aos system sleep

version

`aos version`

Print the aos version

aos version

watch

`aos watch clipboard [--interval=<500ms>] [--max=<n>] [--content]`

Print a JSON line whenever the clipboard text changes

needs a display

aos watch clipboard
aos watch clipboard --max=1 --content

`aos watch file <path> [--interval=<500ms>] [--max=<n>] [--recursive]`

Print a JSON line whenever a file or directory entry changes

needs a display

aos watch file ~/Downloads
aos watch file ./notes.md --max=1
aos watch file ./src --recursive --interval=1s

`aos watch window [--interval=<500ms>] [--max=<n>]`

Print a JSON line whenever the focused window changes

needs a display

aos watch window
aos watch window --max=1

webapp

`aos webapp open <url>`

Open a URL in a chromeless app window

needs a display

aos webapp open https://app.slack.com

window

`aos window arrange <layout.json>`

Apply a saved layout of many windows in one pass

needs a display

aos window arrange ~/.config/aos/layouts/work.json

`aos window focus <app> | --app=<name> | --title=<substring>`

Bring a window to the front

needs a display

aos window focus Chrome

`aos window list [--app=<name>] [--title=<substring>] [--json]`

List open windows

needs a display

aos window list
aos window list --app=Chrome

`aos window move <app> (--zone=<1A|2:1> | --at=<x,y,w,h>) [--monitor=<n>]`

Move a window to a zone, a split, or absolute bounds

needs a display

aos window move Chrome --zone=1B
aos window move Chrome --monitor=2 --zone=1:3
aos window move Slack --at=0,25,1920,1055

`aos window resize <app> --w=<width> --h=<height>`

Resize a window in place

needs a display

aos window resize Chrome --w=900 --h=700

`aos window save <layout.json> [--app=<name>] [--monitor=<n>]`

Save the current layout to a file window arrange can apply

needs a display

aos window save ~/.config/aos/layouts/work.json
aos window save ~/work.json --app=Chrome
aos window save ~/second-screen.json --monitor=2

`aos window wait <app> [--timeout=<ms>]`

Wait for a window to appear, then print it

needs a display

aos window wait Chrome --timeout=5000

`aos window zones [--monitor=<n>] [--show]`

Show what each zone means on a real monitor

needs a display

aos window zones
aos window zones --monitor=2
aos window zones --show --app=Chrome