@ace-sdk/cli

Command-line tool for ACE pattern learning — ACE 1.5 / v4.0.0.

Installation

npm install -g @ace-sdk/cli

Features

• 37+ Commands: patterns, search, learn, bootstrap, traces, cache, and more
• ACE 1.5 Tier Reward Model: cumulative_v15_reward + n_hot/warm/cold tier counters replace the old helpful/harmful headline metrics
• F-080 Feedback Loop: --pin-session on search saves retrieval_id + per-pattern retrieval_log_id; --pin-session / --applied-log-ids on learn closes the bandit loop
• Task-Intent Routing: --task-intent refactor|routine|explore|spec_strict hints the LinUCB bandit
• 7-Day SQLite Graph Cache: per-(org, project) DB at ~/.ace-cache/<org>__<project>.db with flat 2-hop neighbors() query — local data source for ace-desktop Brain-Graphs
• --expand-neighbors: opt-in flag on search that attaches an expanded array of id-only stubs (up to 2-hop graph neighbors) to the result — deduped against primary hits, token-efficient context expansion
• Multi-Org Support: work with multiple organizations and projects
• JSON Output: automation-friendly structured output

Quick Start (ACE 1.5)

# Authenticate
ace-cli login

# View patterns (scores shown as +N.NN tier reward)
ace-cli patterns

# Search — hint bandit + pin session for F-080 feedback
ace-cli search "authentication best practices" \
  --task-intent refactor \
  --pin-session my-session-1

# Search with graph neighbor expansion (attaches expanded[] in --json output)
ace-cli search "authentication best practices" --expand-neighbors --json

# Bootstrap playbook from existing codebase
ace-cli bootstrap --mode hybrid

# Submit learning with F-080 feedback (closes the bandit loop)
ace-cli learn \
  --task "Implemented JWT refresh rotation" \
  --success \
  --output "Token rotation prevents theft" \
  --pin-session my-session-1

ACE 1.5 — What Changed from 1.0

| 1.0 | 1.5 replacement | |-----|----------------| | --min-helpful <n> | --min-reward <n> (on patterns and top) | | helpful / harmful as headline metrics | cumulative_v15_reward / tier counters (PRIMARY) | | No retrieval feedback | --pin-session + --applied-log-ids on learn | | 5-min KV cache | 7-day SQLite graph cache (~/.ace-cache/<org>__<project>.db) |

ACE 1.5 is a clean-break MAJOR release — no 1.0 compat shim in the write path. Legacy 1.0 patterns stored on the server are decoded gracefully on read.

F-080 Feedback Loop

The F-080 loop teaches ACE which patterns your agent actually applied.

ACE 1.5 server-side stamping: when --pin-session <id> is used on search, the CLI includes session_id in the POST /patterns/search request body. The server writes this value into retrieval_log_v15.session_id for every matched pattern at query time, creating a durable server-side link to the later learn call. Prior to ACE 1.5 this column was always NULL.

# 1. Search and pin the session
#    session_id is sent in the POST /patterns/search body so the server stamps
#    retrieval_log_v15.session_id for every matched row at search time.
ace-cli search "JWT refresh" --pin-session task-$(date +%s)

# 2. Do your work...

# 3. Learn with feedback — retrieval_id + applied retrieval_log_ids are
#    recalled from the pinned session and sent on /traces
ace-cli learn \
  --task "Implemented JWT auth" \
  --success \
  --output "Used refresh token rotation" \
  --pin-session task-$(date +%s)

# Alternatively, supply IDs explicitly from --json search output
ace-cli learn \
  --task "Implemented JWT auth" \
  --success \
  --output "Used refresh token rotation" \
  --retrieval-id "550e8400-e29b-41d4-a716-446655440000" \
  --applied-log-ids "47870,47871"

Commands Overview

| Command | Description | |---------|-------------| | patterns | View playbook patterns (tier reward scores) | | search | Semantic search — --task-intent, --pin-session, --expand-neighbors, exploration flags | | learn | Submit trace — --pin-session, --retrieval-id, --applied-log-ids | | top | Show top-rated patterns | | bootstrap | Initialize playbook from codebase | | status | Show playbook statistics | | traces list/get | Browse execution traces | | cache clear/recall | Manage 7-day SQLite graph cache | | config | Configure server connection | | doctor | Run diagnostics | | login / logout / whoami | User authentication | | orgs / switch-org | Organization management |

Documentation

Full documentation: sdks/typescript/cli/docs

See also: Root README for complete multi-language SDK information.

License

MIT © CE.NET Team