Your first application

Create a project, add an app and serve its first route. Start here if you are new to Cicadel.

You need Go 1.26.11 or later and PostgreSQL 18. The standard project includes accounts, so runtime commands need a database.

#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 Cicadel version this documentation describes 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

Run these commands from the directory that will contain myapp:

export GOPRIVATE=github.com/fauzaanu/cicadel
go run github.com/fauzaanu/cicadel/cmd/cicadel@v0.2.7 startproject myapp example.com/myapp
cd myapp
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 you continue.

• Access. The repository is private. Configure Git credentials with access, and set GOPRIVATE as shown.
• Versions. The generated go.mod pins the framework and core modules at the CLI’s release. Commit go.mod and go.sum to keep it.
• Project CLI. Inside the project, go tool cicadel runs 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. Keep 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.

Unlike Django’s INSTALLED_APPS strings, this is a Go list of app values. 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),
    )
}

List the apps, run the checks and tests, then start the server:

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

Fetch the route from a second terminal:

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 you rebuild. 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.

#Deploy

Build the server with go build -o bin/server .. Then follow deployment configuration.