CLI and App

App is a singleton instance of Astal.Application.

import { App } from "astal"

Entry point

app.ts

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")
    },
})

ags

ags -m "say hi"
# hi cli

astal

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.

main.ts

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")
    },
})