Terminal client for Tree. A context management system for organizing AI, data, and ideas into living structure. Navigate your trees like a filesystem. Run multiple AI conversations in parallel. Connect to any Land, browse the canopy network, and work across federated trees from one terminal.
npm install -g treeostreeos connect http://localhost:3000 # point at your Land (or skip for treeOS.ai)
treeos login --key YOUR_API_KEY # get your key from your Land
treeos start # launch the interactive shellroots # list your trees
root Life Plan # enter a tree
ls # list children
mkdir Health, Work, Projects # create nodes
cd Health # navigate deeper
chat make me a weekly workout plan
tree # see the structure it built
cd Workouts # go into a node it created
place did 20 pushups today # AI logs it in the right spot
note stretch before next session
@fitness how's my bench # named session, pinned here
cd /Projects # navigate away
@fitness add 5 reps to last set # still talks to Health/Workouts
sessions # see all active sessions
cd / # go to Land root
home # back to user home
exit # leave the shell
| Command | Description |
|---|---|
connect <url> |
Set Land URL (e.g. http://localhost:3000) |
start / shell |
Launch interactive shell |
stop / exit |
Exit the shell |
login --key <key> |
Authenticate with your API key |
logout |
Clear stored credentials |
whoami |
Show login, plan, energy, and active tree |
help |
Refresh available commands and show help |
protocol |
Show land capabilities, extensions, command count |
Named conversations pinned to positions. Start a session anywhere, navigate away, come back to it from anywhere. Each session maintains its own AI context at its pinned position.
| Command | Description |
|---|---|
@name <message> |
Send a message to a named session. Creates it if new. |
@name |
Switch to a named session (prompt updates) |
@default |
Switch back to default session (follows navigation) |
sessions |
List all active sessions with positions |
sessions kill <handle> |
End a named session |
Sessions are pinned to the position where they were created. @fitness created at /Health/Fitness always talks to that position, even if you navigate to /Projects. The AI responds with the full context of the pinned branch.
Navigating with cd switches back to the default session. Named sessions stay alive. @fitness from anywhere brings you right back.
In the shell, the prompt shows your active session:
tabor@treeos.ai/MyTree @fitness >
AI has full context of the branch you're in. Works in remote trees too.
| Command | Description |
|---|---|
chat <message> |
Chat with AI about the current branch |
place <message> |
AI writes content into the branch |
query <message> |
Ask AI about the branch (read-only, no writes) |
chats |
Chat history for current node. -l limit |
chats tree |
All chat history across the whole tree |
Use @name for named sessions (see Sessions above). @fitness hello is the natural way. chat is for messages at the current position without a session name.
At / you see the Land. System nodes (.identity, .config, .peers) appear alongside your own trees, shared trees, and public trees.
| Command | Description |
|---|---|
cd / |
Go to Land root from anywhere |
ls / ls -l |
List system nodes + your trees + shared trees + public trees |
cd <name> |
Enter a tree or system node |
config |
View Land runtime configuration |
config set <key> <val> |
Set a config value (admin only) |
Your home screen before entering a tree.
| Command | Description |
|---|---|
roots |
List all your trees |
use <name> / root <name> |
Enter a tree by name or ID |
mkroot <name> |
Create a new tree |
retire/leave [name] -f |
Leave a shared tree or delete if sole owner |
home |
Leave current tree, return home |
invites |
List pending invites from other users |
tags / mail |
Notes where you've been @tagged |
notes |
Your user-level notes. -l limit, -q search |
chats |
All AI chats across your trees. -l limit |
contributions |
Your recent contributions |
share-token [token] |
Show or set your share token |
Capture ideas from anywhere. AI figures out where they belong.
| Command | Description |
|---|---|
ideas |
List ideas. -p pending, -r processing, -s stuck, -d done, -a all, -q search, -l limit |
cat idea <id or #> |
View full content of a raw idea |
idea <message> |
AI places your idea in the right tree and navigates you there |
idea-store <message> |
Save an idea for later without processing |
idea-place <id or message> |
AI-place an idea (fire-and-forget) |
idea-auto [on/off] |
Toggle auto-placement every 15 min (Standard plan+) |
idea-transfer <id> <nodeId> |
Manually move an idea to a specific node |
rm-idea <id> -f |
Delete a raw idea |
Move through your tree the way you'd move through a filesystem. Works in local and remote trees.
| Command | Description |
|---|---|
pwd |
Print current path (includes @domain prefix when in a remote tree) |
ls / ls -l |
List children. Long format shows IDs and status |
cd <name> |
Navigate into a child. Supports .., /, -r (search whole tree), path chaining (A/B/C) |
cd @domain/tree |
Enter a public tree on a remote land via the canopy proxy |
cd @domain |
List public trees on a remote land |
tree |
Render subtree. -a active, -c completed, -t trimmed |
cc |
Open the command center (tools, modes, extensions at this position) |
Nodes have three statuses: active (green), completed (gray), trimmed (dim).
When inside a remote tree (prompt shows @domain), all commands route through the canopy proxy to the remote land.
Build and reshape your tree structure.
| Command | Description |
|---|---|
mkdir <name> |
Create child node(s). Comma-separate for multiple: mkdir foo, bar |
rm <name> -f |
Delete a node (soft delete) |
rename <name> <new> |
Rename a child node |
mv <name> <destId> |
Move a node to a new parent |
complete |
Set current node and all children to completed |
activate |
Set current node and all children to active |
trim |
Set current node and all children to trimmed |
prestige |
Create a new version of the current node |
Every note adds context the AI can work with. Values track anything quantitative.
| Command | Description |
|---|---|
note <content> |
Post a note on the current node |
notes |
List notes on the current node. -l limit, -q search |
cat note <id or #> |
View full content of a note |
rm-note <id> -f |
Delete a note |
book |
Print the full book of notes from current node down |
contributions |
List contributions on the current node |
values |
List values on the current node. -g global totals, -t per-node tree breakdown |
value <key> <val> |
Set a value |
goal <key> <goal> |
Set a goal |
Date: MM/DD/YYYY. Time: HH:MM or HH:MMam/pm. Reeffect: hours. Use clear to remove.
| Command | Description |
|---|---|
schedule <date> [time] [reeffect] |
Set schedule (e.g. 1/11/2025 3, 1/11/2025 11:45pm 5, clear) |
calendar |
Show scheduled dates. -m month (1-12 or name), -y year |
dream-time <HH:MM> |
Set nightly dream time (or clear) |
Work on trees with other people. Use user@domain to invite users on other lands.
| Command | Description |
|---|---|
team |
Show owner and contributors. Remote users show @domain |
invite <username> |
Invite a local user to the current tree |
invite <user@domain> |
Invite a user from a remote land |
invite accept <id> |
Accept a pending invite |
invite deny <id> |
Decline a pending invite |
kick <username> |
Remove a contributor |
owner <username> |
Transfer tree ownership |
Clickable terminal hyperlinks. link uses your share token; share generates public links.
In a tree:
| Command | Description |
|---|---|
link |
Link to current node |
link root |
Link to tree root |
link book |
Link to book view |
link gateway |
Link to gateway channels |
link note <id> |
Link to a specific note |
share note <id> |
Public link to a note |
share book |
Public book share link (TOC included) |
From home:
| Command | Description |
|---|---|
link |
Link to your profile |
link ideas |
Link to your raw ideas |
link idea <id> |
Link to a specific raw idea |
Compress a branch into a structured encoding the AI can reference.
| Command | Description |
|---|---|
understand [perspective] |
Start an understanding run. Returns final encoding |
understandings |
List runs |
understand-status <runId> |
Check progress |
understand-stop <runId> |
Stop a run |
Connect to peer lands, discover trees across the network, and navigate into remote trees.
| Command | Description |
|---|---|
peers |
List known peer lands |
peer add <url> |
Peer with a land by URL |
peer remove <domain> |
Remove a peer |
peer block <domain> |
Block a peer land |
peer unblock <domain> |
Unblock a peer land |
peer discover <domain> |
Look up a land on the Horizon and auto-peer |
peer ping |
Heartbeat check all peers |
search [query] |
Search the Horizon for public trees |
search -l [query] |
Search for lands instead of trees |
browse <domain> [query] |
List public trees on a specific peer land |
cd @domain/treename |
Enter a remote tree (all commands proxy through) |
cd @domain |
List public trees on a remote land |
Once inside a remote tree, your shell prompt shows the @domain prefix and all commands route transparently through the canopy proxy.
No login required.
| Command | Description |
|---|---|
blogs |
List published posts |
blog <slug or number> |
Read a post by slug or list number |
Install, manage, and build modular capabilities. Commands from installed extensions appear automatically after help refreshes the protocol.
| Command | Description |
|---|---|
ext list |
List loaded extensions with status |
ext info <name> |
Show manifest details |
ext search [query] |
Search the extension registry |
ext view <name> |
View registry extension (files, manifest) |
ext install <name> |
Install from registry (auto-resolves deps) |
ext update <name> |
Update to latest version |
ext disable <name> |
Disable (takes effect on restart) |
ext enable <name> |
Re-enable a disabled extension |
ext uninstall <name> |
Remove extension directory (data stays in DB) |
ext publish <name> |
Publish to the registry |
Install entire capability bundles or full OS distributions in one command.
| Command | Description |
|---|---|
bundle list |
List available bundles from the directory |
bundle info <name> |
Full details, member list, size estimate |
bundle install <name> |
Install all member extensions |
os list |
List available OS distributions |
os info <name> |
Everything it installs, configures, and expects |
os install <name> |
Install everything: bundles, extensions, config |
Control what the AI can do and how it thinks at every node. Inherits parent to child.
| Command | Description |
|---|---|
tools |
Show effective tools at current node |
tools-allow <tool> |
Add a tool to this node (e.g. execute-shell) |
tools-block <tool> |
Block a tool at this node (e.g. delete-node-branch) |
tools-clear |
Remove all local tool config (inherit from parent) |
modes |
Show mode overrides and available modes |
mode-set <intent> <modeKey> |
Override a mode for an intent at this node |
mode-clear [intent] |
Clear mode override(s) |
ext-scope |
Show active/blocked extensions at current node |
ext-scope -t |
Show block map across entire tree |
ext-block <name> |
Block an extension at this node (inherits down) |
ext-allow <name> |
Allow a confined extension at this node |
| Command | Description |
|---|---|
llms |
List your LLM connections |
llm add |
Add a new connection (interactive) |
llm remove <id> |
Remove a connection |
llm assign <slot> <id> |
Assign to user slot (main) |
llm tree-assign <slot> <id> |
Assign to tree slot (default, respond, etc.) |
llm failover |
Show your failover stack |
llm failover-push <id> |
Add backup connection |
llm failover-pop |
Remove last backup |
llm tree-failover |
Show tree failover stack |
llm tree-failover-push <id> |
Add backup to tree |
llm tree-failover-pop |
Remove last tree backup |
View and manage runtime configuration for the Land. Settings stored in the .config system node.
| Command | Description |
|---|---|
config |
Show Land URL and all config |
config show |
Show all config values |
config get <key> |
Get a single config value |
config set <key> <val> |
Set a config value (admin only) |
All commands accept names or IDs. No quotes needed for multi-word names. Matching order:
- Exact ID or ID prefix
- Exact name (case-insensitive)
- Name starts with query
- Name contains query
Multiple matches prompt you to disambiguate by ID.
root Fitness
cd Workouts
@fitness track my bench progress # creates @fitness pinned here
cd /Projects/Backend
@work what's the status on the API # creates @work pinned here
@fitness add 5 reps to bench # talks to Workouts from Projects
@work prioritize the auth refactor # talks to Backend from Projects
sessions # see both sessions
@default # back to following navigation
root Startup
chat I need to plan a product launch for March --
landing page, email sequence, social, and a demo video
tree # see what it built
cd Launch/Landing Page
note hero section should lead with the compression angle
Don't pre-build the tree. Describe what you need and let AI create the hierarchy, then navigate into it and start adding detail.
idea we should batch API calls to reduce token waste
idea the onboarding flow feels too long
idea what if nodes could have expiration dates
ideas # see what's pending
ideas -d # check what landed
Ideas don't need a tree selected. AI matches each one to the right tree and places it. Check back later to see where things ended up.
root Fitness
cd Workouts/Pushups
value reps 20
cd /Workouts/Running
value miles 3.1
cd /
values -g # totals across every branch
values -t # per-node breakdown
goal miles 100
Values roll up. Set them deep in the tree, read them from anywhere.
root Product
cd Roadmap
understand what are the open questions and blockers
An understanding run reads every node and note under the branch and returns a compressed encoding. Useful before planning sessions or when a branch gets deep.
root Team Wiki
invite alex
invite sara@other-land.com # invite from another land
team # see contributors (remote users show @domain)
notes -q "auth" # find what others added
tags # see where you've been @mentioned
peers # see connected lands
peer add https://friend.land # connect to a new land
search machine learning # find public trees across the network
browse friend.land # see what's public on a specific land
cd @friend.land/Research # enter a remote tree
ls # browse it like your own
note interesting approach here # leave a note (if you have access)
cd / # back to your Land
When you cd @domain/treename, the CLI proxies all operations through the canopy. The remote land handles auth and access.
treeos start
root Life
calendar # what's scheduled today
cd -r Workouts # jump straight there
place ran 5k, felt good
@fitness log bench 135x8, 155x5 # quick session note from anywhere
cd /
dream-time 9:30pm # AI cleans up tonight
cd Projects/Blog Post
book # preview the full book of notes
share book # get a public link
link gateway # open the gateway view
treeos connect http://localhost:3000 # self-hosted Land
treeos login --key YOUR_KEY
treeos startIf you skip connect, the CLI defaults to https://treeOS.ai.
These appear when the extension is installed. Run help to refresh.
| Command | Extension | Description |
|---|---|---|
scout <query> |
scout | Triangulate across the tree with five search strategies |
explore <query> |
explore | Navigate downward through a branch to find information |
explore deep <query> |
explore | More iterations, lower confidence threshold |
explore map |
explore | Last exploration map at this position |
trace <concept> |
trace | Follow one thread through the entire tree chronologically |
changelog |
changelog | What changed at this branch. --since 7d, --land |
digest |
digest | Today's daily briefing from the tree |
delegate |
delegate | Pending work suggestions for team members |
competence |
competence | Knowledge boundaries at this position |
governance |
governance | Governance status for all configured directories |
evolve |
evolve | Detected patterns and extension proposals |
flow |
flow | Cascade signals scoped to current position |
inverse |
inverse-tree | Your profile as the AI sees it |
intent |
intent | Autonomous intent queue and recent executions |
intent pause |
intent | Pause autonomous behavior on this tree |
intent history |
intent | What the tree did on its own |
Sessions are the most powerful feature of the CLI. They let you hold multiple parallel conversations at different positions in the tree, switch between them instantly, and never lose context.
@fitness how's my bench press progress
This creates a session called fitness, pins it to your current position, and sends the message. The AI responds with full context of that branch. You can navigate anywhere else and keep talking to it.
Without sessions, the AI context follows your navigation. cd somewhere and the AI forgets where you were. Sessions break that coupling. The AI at @fitness always thinks from the position where you created it, regardless of where you are now.
cd Health/Fitness
@fitness what should I do today
cd /Work/Backend
@work what's blocking the auth refactor
cd /Life/Journal
@journal I've been thinking about balance
@fitness add 10 lbs to squat
@work create a ticket for the token migration
@journal that felt good to write down
Three sessions. Three positions. Three AI contexts. You're standing at /Life/Journal but talking to all three branches. Each one responds from its own position with its own tools, modes, and context.
@fitness hellosends a message to the fitness session@fitnessalone (no message) switches your active session. The prompt changes. All subsequentchatcommands go to that session without the prefix.@defaultswitches back to the default session that follows your navigation.
tabor@treeos.ai/Life/Journal @fitness >
This means: you're at /Life/Journal but your active session is @fitness. A plain chat message would go to the fitness session, not to Journal.
@fitness log bench 135x8
cd / # navigate to land root
@fitness and squats 225x5 # still talks to Health/Fitness
home # go to user home
@fitness what's my weekly total # still talks to Health/Fitness
The session doesn't care where you are. It talks to where it was born.
sessions # list all active sessions
sessions kill fitness # end a session
@default # back to following navigation
Navigate when you want to work at a position. cd Work/API and then chat, note, place. The AI context matches where you are.
Use sessions when you want to talk to multiple positions without navigating back and forth. @fitness from anywhere. @work from anywhere. The AI remembers.
Imagine three trees: Health, Work, Personal.
@health log my run today, 5k in 28 minutes
@work the deploy finished, update the status
@journal feeling productive today
Three trees. Three conversations. One terminal. Each session holds its own tree root, node position, and AI context. You never navigate between trees. The sessions are your portals.
With the intent extension installed, sessions become even more powerful:
@fitness what did the tree do overnight
The AI at @fitness checks intent history for the Health tree and tells you: "Intent compressed the old workout logs and nudged you about running." You didn't navigate there. You asked from wherever you were.
With delegate installed:
@team-api any delegate suggestions for me
The AI checks delegate suggestions near your session position and tells you what needs attention.
Sessions turn the CLI from a navigation tool into a command center. You don't go to the work. The work comes to you.
All commands map to the Tree REST API. Named sessions use sessionHandle to maintain conversation context across messages. Remote tree operations route through the Canopy protocol via /canopy/proxy/:domain/*. Config stored in ~/.treeos/config.json.