alforria

Quickstart

Connect a provider, choose a model, and start your first alforria session.

This walkthrough installs the working parts in order: a provider, a model, and a first session. Run the commands from the repository you want to work in.

1. Connect a provider

alforria auth login

The prompt asks which provider to use, then walks through its login method. auth is an alias for providers, so these are equivalent:

alforria providers login
alforria auth login

To skip provider selection, name it directly:

alforria auth login -p libertai

LibertAI uses a browser sign-in flow. If the browser runs on another machine, sign in there and paste the code at the prompt: the value after code=, or the whole redirect URL. Other providers use their documented API key or OAuth flow. List configured credentials at any time:

alforria auth list

Credentials are stored in alforria's auth store, not in the project.

2. Choose a model

alforria models
alforria models libertai

Model ids use the provider/model form, for example libertai/<model-id>. To refresh the cached catalog from models.dev:

alforria models --refresh

You can override the model for one launch with -m:

alforria -m libertai/<model-id>

3. Start the terminal UI

alforria

The TUI opens in the current directory. Type a request and press Enter. The command palette is ctrl+p; the leader key is ctrl+x. From the palette you can create sessions, switch models and agents, compact the conversation, and change themes.

If you only need one answer, use a non-interactive run:

alforria run "summarize this repository and its test commands"

Print raw JSON events instead of formatted output:

alforria run --format json "list the top-level directories"

4. Open the web client

alforria web

This starts a local server on 127.0.0.1 and opens the browser UI. The same sessions are available in the TUI and the web client.

alforria web does not generate a password. Unless OPENCODE_SERVER_PASSWORD is set, it prints OPENCODE_SERVER_PASSWORD is not set; server is unsecured and runs without authentication, so any program that can reach the port can use the API. To protect it, set a password first:

OPENCODE_SERVER_PASSWORD='a-long-secret' alforria web

To start a headless server without opening a browser:

alforria serve --port 4096

Open http://localhost:4096 for the embedded client. When OPENCODE_SERVER_PASSWORD is not set, serve generates a password and prints it once with the username. The username is alforria, or the value of OPENCODE_SERVER_USERNAME. Keep the password private.

5. Continue or attach

Continue the most recent session:

alforria -c

Resume a specific session and fork it before the next turn:

alforria -s <session-id> --fork

Attach the TUI to a running server:

alforria attach http://localhost:4096

For a remote server, pass the credentials explicitly:

alforria attach http://workstation:4096 -u alforria -p "$OPENCODE_SERVER_PASSWORD"

Permissions and auto-approval

Tool calls follow the permission rules in your configuration. When a call is set to ask, alforria pauses and shows the request. You can allow it once, always, or reject it.

--auto approves every permission that is not explicitly denied:

alforria --auto

This is dangerous. Use it only in an environment you are prepared to lose. See Configuration for permission rules.

Next steps