Use the Chainabit CLI

In this tutorial you will install the Chainabit CLI, sign in, set up a productivity workflow (Chainy → Chain → Bits), run an AI analysis, and start an interactive Chao session. By the end you will have a full terminal workflow from authentication to AI-powered insights.

Prerequisites

• Node.js 18 or later
• npm or pnpm installed
• A Chainabit account

---

Step 1: Install the CLI

Install globally with npm or pnpm:

npm install -g @chainabit/cli
# or
pnpm add -g @chainabit/cli

Confirm the install:

chainabit --version

Expected output: @chainabit/cli 1.x.x (exact version may vary).

---

Step 2: Sign In

The default login flow opens a browser tab:

chainabit auth login

If you are working in a headless environment (a server, container, or CI), use a developer token instead. Create one at Developer Access, then pass it at login:

export CHAINABIT_TOKEN="cbt_live_..."
chainabit auth login --token-env CHAINABIT_TOKEN

Verify the session:

chainabit auth whoami

Expected output:

Logged in as: yourhandle
Plan: Starter
AI credits: 2,500

---

Step 3: List and Pin a Workspace

Workspaces group your Chains, Bits, and agent resources. List your workspaces and pin the one you want to work in:

chainabit workspace list

Output:

ws_01HQA...   Personal Workspace     (default)
ws_01HQB...   Work Projects

Pin the workspace you will use throughout this tutorial:

chainabit workspace use ws_01HQA...
chainabit workspace current

Output: Current workspace: Personal Workspace (ws_01HQA...)

---

Step 4: Create a Chainy

A Chainy is a goal system that groups one or more related Chains. Create one:

chainabit chainy create --title "Reading Goals"

Output:

Created Chainy: Reading Goals (cy_01HQC...)

Save the ID:

export CHAINY_ID="cy_01HQC..."

List your chainies to confirm:

chainabit chainy list

---

Step 5: Create a Chain

A Chain is a trackable workflow under a Chainy — it holds Bits and tracks streaks:

chainabit chain create --title "Daily Reading" --chainy "$CHAINY_ID"

Output:

Created Chain: Daily Reading (ch_01HQD...)

Save the ID:

export CHAIN_ID="ch_01HQD..."

Check the current streak (should be 0 on a new Chain):

chainabit chain streak "$CHAIN_ID"

---

Step 6: Add and Complete Bits

Bits are the atomic tasks that move a Chain forward. Add two Bits:

chainabit bit create --title "Read 20 pages" --chain "$CHAIN_ID"
chainabit bit create --title "Write a summary" --chain "$CHAIN_ID"

List the Bits on the Chain:

chainabit bit list --chain "$CHAIN_ID"

Output:

bit_01HQE...   Read 20 pages       pending
bit_01HQF...   Write a summary     pending

Mark the first Bit as completed:

chainabit bit complete bit_01HQE... --notes "Finished chapters 3 and 4"

Output:

Completed: Read 20 pages (bit_01HQE...)

List again — the first Bit is now completed:

chainabit bit list --chain "$CHAIN_ID"

---

Step 7: Request an AI Suggestion

Ask Chao to suggest an improvement for the Chain:

chainabit ai suggest create --chain "$CHAIN_ID"

Output:

Created suggestion: sug_01HQG...
Suggestion: Consider adding a reflection bit — 5 minutes of journaling after reading improves long-term retention.

---

Step 8: Chat with Chao

Start an interactive Chao session for your Chain. Chao has context about your Bits and progress:

chainabit chao --message "I completed reading today. What should I do tomorrow?"

Chao responds in your terminal with a streaming reply.

For a multi-turn conversation, start without a message to enter interactive mode:

chainabit chao

Type your messages and press Enter. Type exit or press Ctrl+C to end the session.

---

Step 9: Use --json for Scripting

Every command supports --json for machine-readable output. Pipe it to jq for filtering:

# Get the current Chain streak as a number
chainabit chain streak "$CHAIN_ID" --json | jq '.streak'

# List all pending Bits as an array
chainabit bit list --chain "$CHAIN_ID" --json | jq '[.[] | select(.status == "pending")]'

# Check wallet balance in a script
CREDITS=$(chainabit wallet balance --json | jq '.credits')
echo "Remaining credits: $CREDITS"

---

Summary

In this tutorial you:

1. Installed the CLI and signed in via browser or developer token
2. Listed and pinned a workspace
3. Created a Chainy (goal system) and a Chain (trackable workflow)
4. Added and completed Bits with notes
5. Requested an AI suggestion for the Chain
6. Started an interactive Chao session with workspace context
7. Used --json for scriptable output

Next Steps

• CLI Reference for all available commands and flags
• Run the CLI in CI/CD for non-interactive automation patterns
• Create an AI Agent to automate Bit completion with agents