Client setup and first launch

The komp.ac client is a terminal user interface (TUI) for working with komp.ac data. It is a modal, keyboard-driven application that edits table rows, imports and exports CSV, and renders documents without leaving the terminal. It is a member of the komp_ac workspace and talks to the komp.ac server over gRPC; it never stores business data locally beyond the few files it needs to operate.

This chapter covers everything needed to get the client running for the first time: requirements, building, connecting, the files it creates, its startup sequence, and the first screen. Account management (signing in, registering, and changing passwords) has its own chapter.

Documented version: client v0.8.31.

Requirements

• Rust and Cargo — the client builds as part of the komp_ac workspace;
• a running komp.ac server the client can reach (see Server setup and API overview);
• a terminal with truecolor support, so the bundled themes render as intended.

Building and running

From the workspace root:

cargo run --package client

The binary has no subcommands. It loads a local .env file if one is present in the working directory, then starts the interface.

To build a standalone binary:

cargo build --release --package client
# binary at target/release/client

Connecting to the server

The client connects to http://[::1]:50051 by default, which is the same address the server listens on unless GRPC_LISTEN_ADDRESS was changed. Point the client elsewhere with the GRPC_ENDPOINT environment variable:

GRPC_ENDPOINT=http://127.0.0.1:50051 cargo run --package client

You can also put GRPC_ENDPOINT=... in the local .env file. The value must be a full URI including the scheme.

Note

The server must be running and reachable before you can sign in or open data. The client opens its gRPC channel during startup, but authentication itself happens later, when you log in, over the same connection.

Startup sequence

On every start the client, in order:

1. resolves its per-user directories and bootstraps the configuration (see below);
2. loads config.toml and macros.toml;
3. sets the UI language from [i18n] language;
4. warms the client-side Steel runtime used for computed-column previews;
5. installs a panic hook that writes crashes to client_panic.log;
6. initializes the terminal;
7. opens the gRPC channel to the server;
8. restores the stored session if one exists (auto-login), or starts signed out;
9. loads the configured theme and resolves the export directory;
10. shows the Intro screen, adjusting which views are reachable for the signed-in role.

First launch and files

On its first run the client creates its per-user directories and, when a file does not already exist, writes a default copy. Existing files are never overwritten, so upgrades preserve your configuration.

The locations follow your platform’s conventions (resolved with the directories crate). On a typical Linux setup:

Path	Purpose
~/.config/komp_ac_client/config.toml	User configuration
~/.config/komp_ac_client/macros.toml	Action macros
~/.config/komp_ac_client/themes/	Theme files (bundled themes installed here)
~/.config/komp_ac_client/print_templates/	Print templates
~/.local/state/komp_ac_client/auth.token	Stored session token
~/.local/share/komp_ac_client/imports/progress.json	Resumable import progress
~/.local/state/komp_ac_client/client_panic.log	Crash log

On macOS and Windows the same files live under the standard per-user Application Support / AppData locations instead.

The auth.token file is written with owner-only permissions (0600) on Unix. It is created when you sign in, not on first launch.

The Intro screen

The client opens on the Intro screen, which shows the version and four actions:

Action	What it does
Continue	Opens the first table of the currently selected profile
Admin	Opens the administration panel (for structural roles) or the data-entry panel
Authentication	Opens account management: login, register, change/reset password
Documents	Opens the document archive of rendered outputs

Signing in

Choose Authentication to reach the account screen. Signing in, registering, changing a password, and the stored session are documented in Authentication and accounts.

Opening your first table

Continue on the Intro screen opens the first table of your selected profile:

1. it reads the selected profile and fetches that profile’s table catalog;
2. it opens the first table in the catalog as a form buffer;
3. if there is no selected profile, no table, or the load fails, it shows a dialog explaining what to fix.

For a fresh account, select a profile first (from the data-entry or admin panel) so Continue has a target. Non-admin users have their profile selection remembered across runs.

Troubleshooting

Symptom	Cause and fix
Login fails with a connection error	The server is not running or the endpoint is wrong. Start the server and check GRPC_ENDPOINT against GRPC_LISTEN_ADDRESS.
Continue says no profile or no table	Select a profile first; if the profile has no tables, create one in the admin panel.

Continue

• Server setup and API overview — the server the client connects to.
• Authentication and accounts — signing in and accounts.