Getting Started

This guide walks you through installing the Sentrix CLI, setting up your repository, and running your first workflow.

Prerequisites#

The Sentrix CLI requires git and at least one AI coding agent CLI. It can optionally use gh (GitHub CLI) for higher-fidelity PR workflows:

Verify git is installed:

git --version

AI Coding Agent Setup#

You must install and authenticate at least one AI coding agent CLI. Sentrix uses these agents to power code generation, plan review, and implementation workflows.

Claude Code CLI (recommended):

Install Claude Code and authenticate with your Anthropic account:

Mac, Linux, WSL

curl -fsSL https://claude.ai/install.sh | bash

Windows Powershell

irm https://claude.ai/install.ps1 | iex

Authenticate:

claude

Codex CLI:

Install Codex and authenticate with your OpenAI account:

npm install -g @openai/codex

Authenticate:

codex

GitHub CLI (optional)#

If you use GitHub CLI, authenticate it for best results:

gh auth login

WSL Browser Login Prerequisites#

On Windows WSL (Ubuntu), sentrix auth login opens a Windows browser and waits for a local callback in WSL. Install the WSL browser opener packages before using browser login:

sudo apt update
sudo apt install -y wslu xdg-utils

command -v wslview
wslview https://api.sentrix.ai

command -v wslview should print a path, and wslview https://api.sentrix.ai should open your Windows browser.

Installation#

Install the sentrix binary using Cargo:

cargo install sentrix

Verify the installation:

sentrix --version

Repository Setup#

Run sentrix init in the root of your repository to configure Sentrix:

sentrix init

This command does three things:

1. Creates .sentrix/config.toml - Repository-level configuration with your API URL and platform mappings. This file is committed to source control.
2. Creates user-scoped files in your local Sentrix directory - This includes config.toml, config.lock, secrets.enc.json, and secrets.key. These files are local to your machine and should never be committed.
3. Updates .gitignore - Appends .sentrix/plan-index.json and .sentrix/*.lock to keep Sentrix local state out of source control.

User Data Directory#

Sentrix keeps user-scoped data outside your repository. The base directory depends on the operating system that is running the CLI:

Common files in that directory:

• config.toml - User config with your name, email, and optional user-level overrides
• config.lock - Lock file used while updating user config
• secrets.enc.json - Encrypted local secret store
• secrets.key - Local encryption key for the secret store

Interactive Prompts#

During setup, you are prompted for:

• API URL - The Sentrix API endpoint (default: https://api.sentrix.ai)
• API key - Your authentication key (entered as hidden input)
• Name - Your display name for plan authorship
• Email - Your email address for plan authorship
• Platform mappings - Which platform each app in your plans/ directory uses (e.g., nextjs, fastapi, rust-cli, ui-component)
• Architecture doc paths - Documentation files that guide AI-generated plans for each platform

Validating Your Setup#

To verify an existing setup without modifying anything, use the --check flag:

sentrix init --check

This runs a series of checks and reports pass/fail/warn for each:

• Config files exist and have valid schemas
• API URL and key are configured
• Platform mappings are present
• .gitignore includes .sentrix/plan-index.json and .sentrix/*.lock

Verify Authentication#

After setup, sign in with browser OAuth when your organization requires tenant-scoped access:

sentrix auth login

If the browser flow needs more time, increase the callback timeout:

sentrix auth login --timeout 300

The CLI prints a local callback URL such as http://127.0.0.1:17483/callback; do not open that callback URL directly. Complete the login in the browser window opened by the CLI.

Then confirm that your credentials work and the CLI can reach the Sentrix API:

sentrix auth test

A successful response confirms you are authenticated. Add --verbose to see the request URL and response time:

sentrix auth test --verbose

Quick Walkthrough#

Here is a minimal end-to-end workflow from initiative to implementation and commit:

1. Create an Initiative#

An initiative is a high-level goal that groups related requirements:

sentrix initiative new --description "Add user onboarding flow with guided tour and progress tracking"

2. Generate Requirements#

Create a detailed requirements document for a specific app:

sentrix requirements new --app website --description "Guided tour component that highlights key features on first login"

If you want Sentrix to generate the requirement metadata but leave the body empty for manual writing, add --frontmatter-only:

sentrix requirements new --app website --description "Guided tour component that highlights key features on first login" --frontmatter-only

3. Generate Plans#

Break the requirements into actionable implementation plans:

sentrix plans generate plans/website/2026-02/feature-guided-tour/

4. Review a Plan#

Have the AI review a plan for completeness, consistency, and correctness:

sentrix plans review plans/website/2026-02/feature-guided-tour/01-feature-guided-tour-component.md

5. Implement a Plan#

Have the AI implement the plan, including writing code, tests, and running verification:

sentrix code generate plans/website/2026-02/feature-guided-tour/01-feature-guided-tour-component.md

6. Create the Commit#

After reviewing the generated changes, stage the exact snapshot you want to record and let Sentrix generate the final commit message:

git add <paths>
sentrix code commit plans/website/2026-02/feature-guided-tour/

If you only want the assembled message without creating the commit yet:

sentrix --format text code commit --message-only plans/website/2026-02/feature-guided-tour/

Sentrix never auto-stages files for commit, so the currently staged snapshot determines the commit contents.

Each command builds on the previous one, creating a structured workflow from idea to implementation and commit.