Get Started

CLI Reference

The acog binary provides 40+ commands organized into 8 groups for interacting with AgenticCognition from the terminal.

The acog binary provides 40+ commands organized into 8 groups for interacting with AgenticCognition from the terminal.

Global Options

All commands support the following global options:

Option	Short	Description	Default
`--format`	`-f`	Output format: `json`, `table`, `text`	`text`
`--storage`	`-s`	Path to `.acog` storage directory	`$ACOG_STORAGE` or `~/.acog`
`--verbose`	`-v`	Enable verbose output	off
`--help`	`-h`	Show help for any command	--
`--version`	`-V`	Print version information	--

model (9 commands)

Manage living user models and their lifecycle.

Command	Description
`model create`	Create a new living user model
`model show <id>`	Display model details and current lifecycle stage
`model vitals <id>`	Show model health metrics and activity summary
`model heartbeat <id>`	Record an interaction heartbeat to advance the model
`model portrait <id>`	Generate a natural-language portrait of the user
`model soul <id>`	Produce a deep soul reflection across all dimensions
`model consciousness <id>`	Display the consciousness map with active regions
`model list`	List all models in the storage directory
`model delete <id>`	Delete a model and its associated data

Example usage:

# Create a model and capture the ID
MODEL_ID=$(acog model create --format json | jq -r '.id')

# Record a heartbeat with context
acog model heartbeat $MODEL_ID --context "discussing career change"

# Generate a soul reflection
acog model soul $MODEL_ID --format json

belief (12 commands)

Manage beliefs within a living user model. Beliefs have physical properties: confidence, crystallization, entanglement, and conviction gravity.

Command	Description
`belief add <model> <text>`	Add a new belief to the model
`belief show <model> <id>`	Display a single belief with all properties
`belief list <model>`	List all beliefs, optionally filtered by domain
`belief strengthen <model> <id>`	Increase belief confidence with evidence
`belief weaken <model> <id>`	Decrease belief confidence with counter-evidence
`belief connect <model> <a> <b>`	Create an entanglement link between two beliefs
`belief graph <model>`	Visualize the full belief graph
`belief keystones <model>`	Identify keystone beliefs that anchor the system
`belief contradictions <model>`	Detect contradictory belief pairs
`belief crystallize <model> <id>`	Force-crystallize a belief (make it resistant to change)
`belief collapse <model> <id>`	Trigger belief collapse when contradictions are irreconcilable
`belief search <model> <query>`	Search beliefs by text content or domain

Example usage:

# Add beliefs with domain and confidence
acog belief add $MODEL_ID "I value deep work over meetings" --domain work --confidence 0.85
acog belief add $MODEL_ID "Collaboration is essential for innovation" --domain work --confidence 0.7

# Connect related beliefs
acog belief connect $MODEL_ID $BELIEF_A $BELIEF_B --type tension

# Find keystones
acog belief keystones $MODEL_ID --format table

# Detect contradictions
acog belief contradictions $MODEL_ID

self (6 commands)

Explore the self-concept topology -- the landscape of identity.

Command	Description
`self topology <model>`	Generate the full self-concept topology map
`self peaks <model>`	Identify identity peaks (strongest self-beliefs)
`self valleys <model>`	Identify identity valleys (weakest self-beliefs)
`self blindspots <model>`	Detect gaps between self-perception and evidence
`self defended <model>`	Find defended territories resistant to change
`self edges <model>`	Map identity edges and boundaries

Example usage:

# Generate full topology
acog self topology $MODEL_ID --format json

# Find defended territories that resist change
acog self defended $MODEL_ID

pattern (3 commands)

Analyze behavioral patterns and decision fingerprints.

Command	Description
`pattern fingerprint <model>`	Generate a decision-making fingerprint
`pattern fossils <model>`	Excavate behavioral fossils from past interactions
`pattern strata <model>`	Display archaeological strata showing identity layers

Example usage:

# Generate decision fingerprint
acog pattern fingerprint $MODEL_ID

# View archaeological layers of identity
acog pattern strata $MODEL_ID --depth 5

shadow (3 commands)

Map the shadow -- unconscious patterns operating below awareness.

Command	Description
`shadow map <model>`	Generate the complete shadow map
`shadow projections <model>`	Detect projection patterns
`shadow blindspots <model>`	Identify shadow blindspots

Example usage:

# Generate shadow map
acog shadow map $MODEL_ID --format json

# Detect projections (attributes ascribed to others that belong to self)
acog shadow projections $MODEL_ID

bias (2 commands)

Detect and map cognitive bias fields.

Command	Description
`bias field <model>`	Map the active bias field
`bias triggers <model>`	Identify emotional triggers that activate biases

Example usage:

acog bias field $MODEL_ID --format table
acog bias triggers $MODEL_ID

drift (2 commands)

Track longitudinal changes in beliefs, values, and identity.

Command	Description
`drift timeline <model>`	Show drift timeline with change events
`drift tectonics <model>`	Display value tectonic movements over time

Example usage:

# Show how values have shifted
acog drift timeline $MODEL_ID --range 90d

# Track slow tectonic movements of core values
acog drift tectonics $MODEL_ID

predict (3 commands)

Use the prediction engine to anticipate preferences, simulate decisions, and project identity trajectories.

Command	Description
`predict preference <model> <query>`	Predict user preference for a given option
`predict decision <model> <scenario>`	Simulate a decision with options
`predict future <model>`	Project identity trajectory into the future

Example usage:

# Predict preference
acog predict preference $MODEL_ID "Should I take the remote job or the office role?"

# Simulate a decision
acog predict decision $MODEL_ID "career change" --options "stay,switch,freelance"

# Project future trajectory
acog predict future $MODEL_ID --horizon 6m