Your first application ¶

Create a project, add an app, and serve its first route. You need Go 1.26.10+. The standard project includes accounts and requires PostgreSQL 18 for runtime commands.

Ask your agent ¶

Copy this prompt into your coding agent. Change myapp and the module path for your project.

Read https://cicadel.fauzaanu.com/en/dev/llms.txt and its quick-start guide.
Create a Cicadel application in ./myapp with module example.com/myapp.
Use the dev version and record the resolved Go dependency versions.
Add a local notes app, register it in project/apps.go, and serve GET /notes/.
Configure PostgreSQL for the standard account and migration workflow. Do not overwrite an existing project.
Run the application checks and tests, start it locally, and verify /notes/ over HTTP.
Tell me the URL, files changed, and checks that passed.

For another version, use the agent setup page. Its links and prompts follow the documentation version selector.

Create the project yourself ¶

Run these commands from the directory that will contain myapp:

export GOPRIVATE=github.com/fauzaanu/cicadel
go run github.com/fauzaanu/cicadel/cmd/cicadel@main startproject myapp example.com/myapp
cd myapp
go get github.com/fauzaanu/cicadel@main
go mod tidy
export DATABASE_URL='postgres://USER:PASSWORD@localhost/myapp?sslmode=disable'
export CICADEL_DEBUG=true
export CICADEL_SECURE_COOKIES=false
go run manage.go migrate
go run manage.go check
go run manage.go runserver

Open http://127.0.0.1:8000. Stop the server with Ctrl-C before continuing. The repository currently requires authorized GitHub access. Configure Git authentication and GOPRIVATE=github.com/fauzaanu/cicadel for direct module access. There are no tagged releases yet, so @main selects the development branch. Commit go.mod and go.sum to keep the resolved version. Inside the project, go tool cicadel uses that project’s CLI.

Add and register an app ¶

From myapp, create a notes app:

go tool cicadel startapp notes

Add the app to project/apps.go, retaining the core registrations:

package project

import (
    "example.com/myapp/apps/notes"
    "github.com/fauzaanu/cicadel"
    "github.com/fauzaanu/cicadel/contrib/formsets"
    "gorm.io/gorm"
)

func InstalledApps(_ *gorm.DB) ([]cicadel.App, error) {
    return []cicadel.App{
        formsets.App(),
        notes.New(),
    }, nil
}

Change example.com/myapp if you chose a different module path. Creating a folder or importing a package does not register an app; this list does.

Check the route ¶

The generated apps/notes/urls.go connects /notes/ to Index:

func URLs() []urls.Route {
    return urls.Include("/notes", "notes",
        urls.Path("GET", "/", "index", Index),
    )
}

Start the app, then fetch the route from a second terminal:

go run manage.go apps
go run manage.go check
go test -race ./...
go run manage.go runserver

curl http://127.0.0.1:8000/notes/
# {"app":"notes"}

Make changes ¶

For UI changes, install the CSS tool once, then rebuild and check:

go tool cicadel ui css install
go tool cicadel ui build
go tool cicadel ui check --json

Restart the server after rebuilding. For automatic rebuilds and restarts, run go tool cicadel dev instead of runserver.

Choose your next step ¶

• Render a component.
• Add htmx interactions.
• Install a reusable app.
• Add PostgreSQL migrations.
• Start with sign-in screens.

When ready to deploy, build go build -o bin/server . and follow deployment configuration. The local debug and insecure-cookie settings above are for development only.