astal/docs/ags/cli-app.md

CLI and App

App is a singleton instance of Astal.Application.

import { App } from "astal"

Entry point

:::code-group

App.start({
    main() {
        // setup anything
        // instantiate widgets
    },
})

:::

:::warning You can not instantiate widgets outside of the main function. :::

Instance identifier

You can run multiple instance by defining a unique instance name.

App.start({
    instanceName: "my-instance", // defaults to "astal"
    main() {},
})

Messaging from CLI

If you want to interact with an instance from the cli, you can do so by sending a message.

App.start({
    main() {},
    requestHandler(request: string, res: (response: any) => void) {
        if (request == "say hi") {
            res("hi cli")
        }
        res("unknown command")
    },
})

:::code-group

ags -m "say hi"
# hi cli

astal say hi
# hi cli

:::

If you want to run arbitrary JavaScript from cli, you can use App.eval. It will evaluate the passed string as the body of an async function.

App.start({
    main() {},
    requestHandler(js: string, res) {
        App.eval(js).then(res).catch(res)
    },
})

If the string does not contain a semicolon, a single expression is assumed and returned implicity.

ags -m "'hello'"
# hello

If the string contains a semicolon, you have to return explicitly

ags -m "'hello';"
# undefined

ags -m "return 'hello';"
# hello

App without AGS

As mentioned before AGS is only a scaffolding tool. You can setup a dev environment and a bundler yourself. In which case you won't be using the ags cli to run the bundled scripts. The produced script can run as the main instance and a "client" instance.

The first time you run your bundled script the main function gets executed. While that instance is running any subsequent execution of the script will call the client function.

:::code-group

App.start({
    // main instance
    main(...args: Array<string>) {
        print(...args)
    },

    // every subsequent calls
    client(message: (msg: string) => string, ...args: Array<string>) {
        const res = message("you can message the main instance")
        console.log(res)
    },

    // this runs in the main instance
    requestHandler(request: string, res: (response: any) => void) {
        res("response from main")
    },
})

:::