Getting Started

Install and set up the Sentrix CLI in your repository.

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:

Tool	Status	Purpose
`git`	Required	All repository-scoped VCS and forge operations, including plan activation, cancellation, completion, and the git-only fallback used when `gh` is unavailable or unusable.
`claude` (Claude Code CLI)	Required (at least one AI CLI)	AI-powered code generation, plan review, and other flows configured to run with Claude. Draft-generation commands such as `sentrix requirements new`, `sentrix initiative new`, and `sentrix plans new` use bundled internal prompts instead of repo-installed slash commands.
`codex` (Codex CLI)	Required (at least one AI CLI)	Alternative AI coding agent. Can be selected by Sentrix command/platform configuration instead of or alongside Claude Code.
`gh` (GitHub CLI)	Preferred (optional)	Full-fidelity PR metadata retrieval for `plans complete` and `plans complete --auto`. When `gh` is unavailable or unusable (for example, not installed, not authenticated, or otherwise unusable), the CLI falls back to git-based heuristics that inspect local merge commit history.

Verify git is installed:

bash

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

bash

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

Windows Powershell

bash

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

Authenticate:

bash

claude

Codex CLI:

Install Codex and authenticate with your OpenAI account:

bash

npm install -g @openai/codex

Authenticate:

bash

codex

GitHub CLI (optional)#

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

bash

gh auth login

Installation#

Install the sentrix binary using Cargo:

bash

cargo install sentrix

Verify the installation:

bash

sentrix --version

Repository Setup#

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

bash

sentrix init

This command does four things:

Creates .sentrix/config.toml - Repository-level configuration with your API URL and platform mappings. This file is committed to source control.
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.
Installs the remaining managed Claude Code command to .claude/commands/ - currently /sentrix-requirements-review for sentrix requirements review. sentrix requirements new, sentrix initiative new, and sentrix plans new use bundled internal prompts instead of repo-installed slash commands.
Updates .gitignore - Appends .sentrix/plan-index.json to prevent the local index from being committed.

User Data Directory#

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

OS	User data directory
macOS	`~/.sentrix/`
Linux	`~/.sentrix/`
Windows WSL (Ubuntu)	`~/.sentrix/`
Windows native	`%APPDATA%\sentrix\`

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:

bash

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
The remaining managed Claude Code command file is installed
.gitignore includes the plan index

Verify Authentication#

After setup, confirm that your API key works and the CLI can reach the Sentrix API:

bash

sentrix auth test

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

bash

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:

bash

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:

bash

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:

bash

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:

bash

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:

bash

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:

bash

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:

bash

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:

bash

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.