CommRails CLI

Overview

The CommRails CLI provides command-line access to the Allternit Agent System Rails. Two binaries are available:

allternit-rails — workspace-aware CLI bundled with the Allternit platform
rails — standalone ticket/DAG workflow CLI that works in any directory

Both share the same event-sourced state under .allternit/ and expose peer messaging, work planning, policy gates, ledger inspection, and ticket tracking.

Base command

allternit rails <subcommand>
# or the standalone binary
rails <subcommand>

Use --root <path> with allternit-rails to target a workspace other than the current directory.

Commands

Work orchestration

Command	Description
`plan create <text>`	Create a DAG from natural-language text
`plan refine <dag_id> --delta "..."`	Refine a DAG with a delta description
`plan show <dag_id>`	Show a projected DAG
`dag render <dag_id>`	Render a DAG as JSON or Markdown
`wih list`	List active or ready WIHs
`wih pickup <node_id> --dag <dag_id> --agent <id>`	Pick up a WIH
`wih context <wih_id>`	Print the WIH context pack
`wih sign-open <wih_id> <signature>`	Sign open a WIH
`wih close <wih_id> <status> [evidence...]`	Close a WIH
`work status`	Show DAG/WIH views and derived loops

Policy, gate, and leases

Command	Description
`gate status`	Check gate health
`gate pre-tool <wih_id> <tool> [paths...]`	Check whether a tool call is allowed
`gate rules`	Print the active gate rules
`gate verify`	Verify ledger chain and DAG acyclicity
`gate decision <note>`	Record an agent decision
`gate mutate <dag_id> <note>`	Apply DAG mutations with provenance
`lease request <wih_id> <agent_id> [paths...]`	Request a scoped lease
`lease release <lease_id>`	Release a lease

Peers and messaging

Command	Description
`peer register <name> --vendor <agent-family>`	Register this session as a peer
`peer unregister <id_or_name>`	Remove a peer
`peer list`	List local peers
`peer heartbeat <id_or_name>`	Refresh a peer heartbeat
`peer inbox <id_or_name>`	Listen on a peer’s UDS inbox
`peer send <name> "<message>"`	Send a message to a peer

Steering

Command	Description
`steer checkpoint --cwd <dir>`	Hash `.steering/checkpoint.md` and emit an event
`steer consult --cwd <dir>`	Consult the configured steering backend
`steer commit-gate --cwd <dir>`	Run commit/push approval consult

Ledger, bus, and transport

Command	Description
`ledger tail [n]`	Tail the last N ledger events
`ledger trace --node <id> / --wih <id> / --prompt <id>`	Trace events by scope
`bus send <to> <from> <kind> <payload>`	Send a durable bus message
`bus poll`	Poll pending bus messages
`bus tmux-send <session> <command>`	Send a command to a tmux pane
`bus socket-send <socket> <payload>`	Send a payload to a socket
`transport tmux-inspect`	Inspect tmux transport state
`transport socket-inspect`	Inspect socket transport state

Tickets and tracking

Command	Description
`ticket ready`	List tickets ready for work
`ticket new "<title>"`	Create a ticket
`ticket list`	List tickets
`ticket close <id>`	Close a ticket
`dag block <ticket> <blocker>`	Add a blocking dependency
`ready --explain`	Show ready tickets with blockers

Runner, memory, and maintenance

Command	Description
`runner start`	Start the long-running Rails loop
`runner once`	Run the Rails loop once
`memory learn "<content>" --tags <tags>`	Store persistent memory
`memory recall <id>`	Retrieve a memory
`echo new "<content>"`	Create an ephemeral echo
`compact all`	Run all compaction operations
`kill status`	Show the emergency kill-switch state
`slo --window <minutes>`	Show operation SLO metrics
`doctor`	Verify the Rails toolchain
`init`	Initialize Rails directories in the workspace

Examples

Initialize a workspace

rails init

Output:

initialized: true
stores: [".allternit/ledger/events", ".allternit/leases", ...]

Register a peer and send a message

allternit rails peer register gizzi-session --vendor gizzi
# peer_abc123 ...

allternit rails peer send gizzi-session "Summarize the current DAG"
# delivered: true

Create a plan and inspect the DAG

allternit rails plan create "Refactor the auth module into services"
# prompt_id: prm_xxx
# dag_id: dag_xxx
# node_id: dag_xxx-root

allternit rails plan show dag_xxx

Pick up and close a WIH

allternit rails wih pickup dag_xxx-root \
  --dag dag_xxx \
  --agent agent-1 \
  --role builder
# wih_id: wih_xxx

allternit rails wih close wih_xxx success "tests pass" "lint clean"
# closed

Tail and trace the ledger

allternit rails ledger tail 20
allternit rails ledger trace --wih wih_xxx

Check gate policy before a tool call

allternit rails gate pre-tool wih_xxx str_replace_editor ["src/auth/login.rs"]
# allowed: true

Exit codes

Code	Meaning
`0`	Success
`1`	General CLI or runtime error
`2`	Steering consult returned `STEER` (commit-gate only)
non-zero	Subcommand-specific failure

Configuration

The CLI discovers state under .allternit/ in the workspace root. Environment variables used by the standalone service:

Variable	Default	Description
`ALLTERNIT_RAILS_HOST`	`127.0.0.1`	Bind host for `allternit-rails-service`
`ALLTERNIT_RAILS_PORT`	`3011`	Bind port for `allternit-rails-service`
`ALLTERNIT_RAILS_ROOT`	current directory	Workspace root directory

Get Started

Core Concepts

Gizzi Code CLI

Tools & ACI

Security & Enterprise

Admin API

BYOC Runtime

Surfaces

CI CD

Guides

Cookbooks

Release Notes

Overview

Base command

Commands

Work orchestration

Policy, gate, and leases

Peers and messaging

Steering

Ledger, bus, and transport

Tickets and tracking

Runner, memory, and maintenance

Examples

Initialize a workspace

Register a peer and send a message

Create a plan and inspect the DAG

Pick up and close a WIH

Tail and trace the ledger

Check gate policy before a tool call

Exit codes

Configuration

​Overview

​Base command

​Commands

​Work orchestration

​Policy, gate, and leases

​Peers and messaging

​Steering

​Ledger, bus, and transport

​Tickets and tracking

​Runner, memory, and maintenance

​Examples

​Initialize a workspace

​Register a peer and send a message

​Create a plan and inspect the DAG

​Pick up and close a WIH

​Tail and trace the ledger

​Check gate policy before a tool call

​Exit codes

​Configuration

​Related links

Overview

Base command

Commands

Work orchestration

Policy, gate, and leases

Peers and messaging

Steering

Ledger, bus, and transport

Tickets and tracking

Runner, memory, and maintenance

Examples

Initialize a workspace

Register a peer and send a message

Create a plan and inspect the DAG

Pick up and close a WIH

Tail and trace the ledger

Check gate policy before a tool call

Exit codes

Configuration

Related links