$ 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
Copy

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
Copy

Config file

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

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

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"
Copy

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
Copy

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"
Copy

--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)"
Copy

It is useful for shebangs

#!/usr/bin/env -S ags --run-file
return "hello from a file";
Copy

this throws

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

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;
Copy

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);
Copy

You can import this module and access this variable

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

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

// vars.js
export const myVar = Variable(0);
globalThis.myVar = myVar;
Copy

ags -r "myVar++"
Copy