> ## Documentation Index
> Fetch the complete documentation index at: https://docs.astrakairo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart: Write and Run Your First Kairo Application

> Create a Kairo project from scratch, write your first program, build it with Forge, and run it with the Pulse runtime in just a few steps.

This guide walks you through creating a minimal Kairo application from scratch. By the end you will have a working project that you can build and run locally using the Forge compiler and Pulse runtime.

<Note>
  Make sure you have Forge and Pulse installed before you begin. See the [Installation guide](installation) for setup instructions.
</Note>

## Create your first Kairo app

<Steps>
  <Step title="Create your project directory">
    Create a new directory for your project and navigate into it. Kairo projects are just folders — there is no scaffolding command yet, so you set them up by hand.

    ```bash theme={null}
    mkdir Hello.Kairo
    cd Hello.Kairo
    ```

    Your project will have a simple structure with one manifest file and one source file under `src/`:

    ```
    Hello.Kairo/
    ├── kairo.toml
    └── src/
        └── Hello/
            └── Kairo/
                └── main.ak
    ```
  </Step>

  <Step title="Write the package manifest">
    Create a file named `kairo.toml` in your project directory. This is the package manifest — it tells Forge the name, version, language version, and kind of your project.

    ```toml theme={null}
    manifest_version = 1

    [package]
    name = "Hello.Kairo"
    version = "0.1.0.0"
    language_version = "0.1"
    kind = "application"
    ```

    <Tip>
      The `kind` field tells Forge how to build your project. Use `"application"` for programs with an entry point and `"library"` for packages meant to be consumed by other projects.
    </Tip>
  </Step>

  <Step title="Write your first Kairo source file">
    Create the file `src/Hello/Kairo/main.ak`. Every Kairo source file starts with a `module` declaration that identifies which module it belongs to. The `main` function is the entry point of your application.

    ```kairo theme={null}
    module Hello.Kairo

    import Pulse.Console

    public func main() {
        Pulse.Console.out.writeLine("Hello, Kairo!")
    }
    ```

    A few things to notice:

    * The `module` declaration matches the `name` in `kairo.toml`
    * `import Pulse.Console` brings in the console I/O module from the Pulse standard library
    * `public` is required on `main` so Forge can resolve it as the entry point
    * Source files use the `.ak` extension and live under `src/`
    * There are no semicolons
  </Step>

  <Step title="Check your code with Forge">
    Before building, run `forge check` to validate your code without producing any output files. This is the fastest way to catch type errors and syntax issues during development.

    ```bash theme={null}
    forge check
    ```

    If everything is correct, you will see output similar to:

    ```
    Checking Hello.Kairo...
    ✓ No issues found.
    ```

    <Tip>
      Use `forge check` frequently while writing code. It is faster than a full build and gives you immediate feedback on errors.
    </Tip>
  </Step>

  <Step title="Build your application">
    Run `forge build` to compile your project. Forge reads `kairo.toml`, restores dependencies, compiles all `.ak` source files, and writes the output to the `build/` directory.

    ```bash theme={null}
    forge build
    ```

    A successful build looks like this:

    ```
    Building Hello.Kairo v0.1.0.0...
    ✓ Build succeeded.
    ```

    Your compiled application is now ready to run.
  </Step>

  <Step title="Run your application with Pulse">
    Use `pulse run` to execute your compiled application with the Pulse runtime.

    ```bash theme={null}
    pulse run
    ```

    You should see your message printed to the console:

    ```
    Hello, Kairo!
    ```

    That's it — you've written, built, and run your first Kairo application.
  </Step>
</Steps>

## Trying different entry point signatures

Kairo supports several valid signatures for the `main` function. You can return an exit code or a `Result` if your application needs to signal success or failure.

```kairo theme={null}
module Hello.Kairo

import Pulse.Console

// Plain entry point — exits with code 0 by default
public func main() {
    Pulse.Console.out.writeLine("Hello, Kairo!")
}

// Return an explicit exit code
public func main(): Int32 {
    Pulse.Console.out.writeLine("Hello, Kairo!")
    return 0
}

// Return a Result to signal success or a typed error
public func main(): Result<Int32, Text> {
    Pulse.Console.out.writeLine("Hello, Kairo!")
    return Result.success(0)
}
```

<Note>
  All three signatures also have `async` variants — for example, `public async func main()` — for applications that need to perform asynchronous work at startup.
</Note>

## What's next?

Now that your first program is running, explore the rest of the language and toolchain.

<CardGroup cols={3}>
  <Card title="Language Syntax" icon="code" href="language/syntax">
    Learn Kairo's syntax, keywords, and core constructs in detail.
  </Card>

  <Card title="Types" icon="shapes" href="language/types">
    Explore Kairo's built-in types and how to define your own value and object types.
  </Card>

  <Card title="Forge CLI" icon="hammer" href="toolchain/forge">
    Master the full Forge command set: restore, build, test, package, and publish.
  </Card>
</CardGroup>