CLI

$ ags --help

USAGE:
    ags [OPTIONS]

OPTIONS:
    -h, --help              Print this help and exit
    -v, --version           Print version and exit
    -q, --quit              Kill AGS
    -c, --config            Path to the config file.
    -b, --bus-name          Bus name of the process
    -i, --inspector         Open up the Gtk debug tool
    -t, --toggle-window     Show or hide a window
    -r, --run-js            Execute string as an async function
    -f, --run-file          Execute file as an async function
    --init                  Initialize the configuration directory
    --clear-cache           Remove $HOME/.cache/ags

Bus Name

It is possible to run multiple instances with --bus-name. It defaults to "ags". When an instance is running, executing ags is actually a client process that will try to connect to the instance with the specified bus name.

ags # starts an instance with bus name "ags"
ags -i # opens up the inspector on the ags instance with bus name "ags"

ags --bus-name test # starts an instance with bus name "test"
ags -b test -i # opens the inspector on instance with bus name "test"

ags --quit
ags -b test --quit

Tip

The dbus name is com.github.Aylur.ags.<bus-name>, so the default one is com.github.Aylur.ags.ags

Config file

--config defaults to $HOME/.config/ags/config.js

# example
ags --config $HOME/.config/some-dir/main.js

Toggle Window

--toggle-window is just there for the sake of it, if you want to have more control use --run-js

# example
ags --toggle-window "bar"

Running arbitrary JavaScript code on runtime

With --run-js it is possible to execute code when ags is already running. It is useful for: calling Service methods, updating Variable values, debugging or anything else. --run-js expects a string which will be the body of an async function executed relative to app.ts.

If there is no ; character in the string, return keyword will be inserted automatically

ags -r "'hello'" # prints hello
ags -r "'hello';" # prints undefined
ags -r "return 'hello';" # prints hello

print will print on the client side, console.log and other console methods will log on the main process’s stdout

ags -r "print('hello')" # prints "hello undefined"
ags -r "console.log('hello')" # prints "undefined"

--run-file reads the content of a file and passes it to --run-js

# these two are equivalent
ags --run-file /path/to/file.js
ags --run-js "$(cat /path/to/file.js)"

It is useful for shebangs

#!/usr/bin/env -S ags --run-file
return 'hello from a file'

Since --run-js is the body of a function, you can’t use top level static imports

The function gets executed relative to app.ts, which means importing a module from your config needs a full path.

this throws

#!/usr/bin/env -S ags --run-file
import Module from 'file:///path/to/file.js' // throws

You can use import as an async method

#!/usr/bin/env -S ags --run-file
const Module = (await import('file:///path/to/file.js')).default;

Examples

Let’s say you have a Variable in $HOME/.config/ags/vars.js that you want set from cli.

vars.js

export const myVar = Variable(0);

You can import this module and access this variable

ags -r "(await import('file://$HOME/.config/ags/vars.js')).myVar++"

Your can make myVar global, to avoid writing out the import statement

vars.js

export const myVar = Variable(0);
globalThis.myVar = myVar;

ags -r "myVar++"