@piut/cli 2.0.0 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +188 -83
- package/dist/cli.js +100 -1240
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,12 +1,8 @@
|
|
|
1
1
|
# pıut
|
|
2
2
|
|
|
3
|
-
**Your AI
|
|
3
|
+
**Your AI brain, everywhere.**
|
|
4
4
|
|
|
5
|
-
pıut
|
|
6
|
-
|
|
7
|
-
1. **Host your brain** — Centralized personal context as an MCP server. Connect once, and every AI tool you use knows who you are, how you work, and what matters to you.
|
|
8
|
-
2. **Keep it updated** — 6 MCP tools let your AI read, write, search, and organize your context automatically. Add a skill reference and it happens without you lifting a finger.
|
|
9
|
-
3. **Back up your files** — Cloud backup of all your agent config files (CLAUDE.md, .cursorrules, AGENTS.md, etc.) with version history, restore, and cross-machine sync.
|
|
5
|
+
pıut builds your personal AI context, deploys it as an MCP server, and connects it to every tool you use. One brain, one API key — Claude, Cursor, Copilot, ChatGPT, and more.
|
|
10
6
|
|
|
11
7
|
## Quick Start
|
|
12
8
|
|
|
@@ -15,16 +11,137 @@ npm install -g @piut/cli
|
|
|
15
11
|
piut
|
|
16
12
|
```
|
|
17
13
|
|
|
18
|
-
The
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
14
|
+
The interactive menu walks you through building your brain, deploying your MCP server, and connecting your AI tools. Or use `npx @piut/cli` to run without installing.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## 1. Install
|
|
19
|
+
|
|
20
|
+
Sign up at [piut.com](https://piut.com) (14-day free trial, no credit card required), then install the CLI:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npm install -g @piut/cli # Install globally
|
|
24
|
+
piut # Interactive menu
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
### CLI Reference
|
|
28
|
+
|
|
29
|
+
| Command | Description |
|
|
30
|
+
|---------|-------------|
|
|
31
|
+
| `piut` | Interactive menu — build, deploy, and connect in one flow |
|
|
32
|
+
| `piut build` | Build or rebuild your brain from your files |
|
|
33
|
+
| `piut deploy` | Publish your MCP server (requires paid account) |
|
|
34
|
+
| `piut connect` | Add brain references to project config files |
|
|
35
|
+
| `piut disconnect` | Remove brain references from project config files |
|
|
36
|
+
| `piut setup` | Auto-detect and configure AI tools (MCP config + skill.md) |
|
|
37
|
+
| `piut status` | Show brain, deployment, and connected projects |
|
|
38
|
+
| `piut remove` | Remove all pıut configurations |
|
|
39
|
+
| `piut sync` | Sync agent config files to the cloud |
|
|
40
|
+
| `piut sync config` | Configure sync settings |
|
|
41
|
+
|
|
42
|
+
#### piut build options
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
piut build # Scan current directory
|
|
46
|
+
piut build --folders src,docs # Scan specific folders
|
|
47
|
+
piut build --key pb_YOUR_KEY # Non-interactive
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
#### piut deploy options
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
piut deploy # Deploy with confirmation
|
|
54
|
+
piut deploy --yes # Skip confirmation
|
|
55
|
+
piut deploy --key pb_YOUR_KEY # Non-interactive
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
#### piut connect / disconnect options
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
piut connect # Add brain refs to project configs
|
|
62
|
+
piut connect --folders src,docs # Scan specific folders
|
|
63
|
+
piut disconnect # Remove brain refs
|
|
64
|
+
piut disconnect --yes # Skip confirmation
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
#### piut setup options
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
piut setup # Auto-detect and configure all tools
|
|
71
|
+
piut setup --tool cursor # Configure a single tool
|
|
72
|
+
piut setup --key pb_KEY --yes # Non-interactive (all tools)
|
|
73
|
+
piut setup --project # Prefer project-local config files
|
|
74
|
+
piut setup --skip-skill # Skip skill.md file placement
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
#### piut sync options
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
piut sync # Show backup status
|
|
81
|
+
piut sync --install # Guided sync setup
|
|
82
|
+
piut sync --push # Push local changes to cloud
|
|
83
|
+
piut sync --pull # Pull cloud changes to local
|
|
84
|
+
piut sync --watch # Watch for changes and auto-push
|
|
85
|
+
piut sync --history <file> # Show version history
|
|
86
|
+
piut sync --diff <file> # Diff local vs cloud
|
|
87
|
+
piut sync --restore <file> # Restore from cloud backup
|
|
88
|
+
piut sync --prefer-local # Resolve conflicts keeping local
|
|
89
|
+
piut sync --prefer-cloud # Resolve conflicts keeping cloud
|
|
90
|
+
piut sync --install-daemon # Set up auto-sync via cron/launchd
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
#### piut sync config options
|
|
22
94
|
|
|
23
|
-
|
|
95
|
+
```bash
|
|
96
|
+
piut sync config --show # View current settings
|
|
97
|
+
piut sync config --files # Change which files are synced
|
|
98
|
+
piut sync config --auto-discover on # Auto-sync new files
|
|
99
|
+
piut sync config --keep-brain-updated on # Keep brain updated from synced files
|
|
100
|
+
piut sync config --use-brain on # Reference centralized brain
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
All commands accept `-k, --key <key>` for non-interactive API key input and `-y, --yes` to skip prompts (where applicable).
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## 2. Build Your Brain
|
|
108
|
+
|
|
109
|
+
Your brain has 5 sections that give AI tools a complete picture of who you are:
|
|
110
|
+
|
|
111
|
+
| Section | What it stores |
|
|
112
|
+
|---------|---------------|
|
|
113
|
+
| **about** | Bio, preferences, goals — the AI's mental model of you |
|
|
114
|
+
| **soul** | Behavioral instructions for AI — tone, guardrails, priorities |
|
|
115
|
+
| **areas** | Long-term life/work domains (Health, Finances, Marketing) |
|
|
116
|
+
| **projects** | Active, time-bound work with goals and deadlines |
|
|
117
|
+
| **memory** | Bookmarks, links, ideas, notes, reference material |
|
|
118
|
+
|
|
119
|
+
Three ways to build your brain:
|
|
120
|
+
|
|
121
|
+
- **CLI:** `piut build` scans your files (CLAUDE.md, .cursorrules, etc.) and builds automatically
|
|
122
|
+
- **Dashboard:** Use the [brain editor](https://piut.com/dashboard/build) to import files, answer questions, or write each section directly
|
|
123
|
+
- **API:** Use `update_brain` or `append_brain` to build programmatically
|
|
124
|
+
|
|
125
|
+
Edits are saved as drafts. When you publish, every connected AI tool sees your updates instantly.
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## 3. Deploy Your Brain
|
|
130
|
+
|
|
131
|
+
Publishing turns your brain into a live MCP server. Requires an active subscription ($10/month after 14-day trial).
|
|
24
132
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
133
|
+
```bash
|
|
134
|
+
piut deploy # Deploy with confirmation
|
|
135
|
+
piut deploy --yes # Skip confirmation
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### Connection Details
|
|
139
|
+
|
|
140
|
+
- **URL:** `https://piut.com/api/mcp/YOUR_SLUG`
|
|
141
|
+
- **Auth (header):** `Authorization: Bearer YOUR_KEY`
|
|
142
|
+
- **Protocol:** JSON-RPC 2.0 (MCP)
|
|
143
|
+
|
|
144
|
+
Standard config for most tools:
|
|
28
145
|
|
|
29
146
|
```json
|
|
30
147
|
{
|
|
@@ -40,109 +157,97 @@ Or set up manually:
|
|
|
40
157
|
}
|
|
41
158
|
```
|
|
42
159
|
|
|
43
|
-
|
|
160
|
+
---
|
|
44
161
|
|
|
45
|
-
##
|
|
162
|
+
## 4. Connect Your Brain
|
|
46
163
|
|
|
47
|
-
|
|
164
|
+
Three ways to connect your brain to your AI tools:
|
|
48
165
|
|
|
49
|
-
|
|
50
|
-
|
|
166
|
+
1. **Via CLI** (easiest): `piut setup` auto-detects tools and configures everything. `piut connect` adds brain references to project configs.
|
|
167
|
+
2. **Via skill.md**: Add a skill reference to your rules file so your AI knows *when* and *how* to use your brain. The CLI adds this automatically.
|
|
168
|
+
3. **Manually**: Edit config files directly for each tool.
|
|
51
169
|
|
|
52
|
-
|
|
53
|
-
piut # Interactive setup: MCP + skill.md + cloud backup
|
|
54
|
-
piut status # Show which tools are connected
|
|
55
|
-
piut remove # Remove pıut from selected tools
|
|
56
|
-
|
|
57
|
-
# Cloud Backup
|
|
58
|
-
piut sync # Show backup status for current workspace
|
|
59
|
-
piut sync --install # Scan workspace, detect files, upload to cloud
|
|
60
|
-
piut sync --push # Push local changes to cloud
|
|
61
|
-
piut sync --pull # Pull cloud changes to local files
|
|
62
|
-
piut sync --history # Show version history for a file
|
|
63
|
-
piut sync --diff # Show diff between local and cloud
|
|
64
|
-
piut sync --restore # Restore files from cloud backup
|
|
65
|
-
```
|
|
170
|
+
For scripting: `piut setup --key pb_YOUR_KEY --yes`
|
|
66
171
|
|
|
67
|
-
**
|
|
172
|
+
**Supported tools:** Claude Code, Claude Desktop, Cursor, Windsurf, GitHub Copilot, Amazon Q, Zed, ChatGPT, OpenClaw, Msty, OpenAI Agents SDK, Claude Agent SDK, and any MCP client.
|
|
68
173
|
|
|
69
|
-
|
|
70
|
-
piut --key pb_... # Pass API key non-interactively
|
|
71
|
-
piut --tool cursor # Configure a single tool
|
|
72
|
-
piut --skip-skill # Skip skill.md file placement
|
|
73
|
-
piut sync --install --yes # Non-interactive backup setup
|
|
74
|
-
```
|
|
174
|
+
### skill.md Reference
|
|
75
175
|
|
|
76
|
-
|
|
176
|
+
Add a reference to [skill.md](skill.md) in your tool's rules file so your AI knows *when* and *how* to use your brain:
|
|
77
177
|
|
|
78
|
-
|
|
178
|
+
| Tool | Add skill.md reference to |
|
|
179
|
+
|------|--------------------------|
|
|
180
|
+
| Claude Code | CLAUDE.md or ~/.claude/CLAUDE.md |
|
|
181
|
+
| Cursor | .cursor/rules/piut.mdc |
|
|
182
|
+
| Windsurf | .windsurf/rules/piut.md |
|
|
183
|
+
| GitHub Copilot | .github/copilot-instructions.md |
|
|
184
|
+
| Claude Desktop | Project Knowledge (upload file) |
|
|
185
|
+
| ChatGPT | Settings > Custom Instructions |
|
|
186
|
+
| Zed | .zed/rules.md |
|
|
187
|
+
| Amazon Q | CONVENTIONS.md |
|
|
188
|
+
| Any other tool | System prompt or rules file |
|
|
79
189
|
|
|
80
|
-
|
|
190
|
+
---
|
|
81
191
|
|
|
82
|
-
|
|
192
|
+
## 5. Use Your Brain
|
|
83
193
|
|
|
84
|
-
|
|
194
|
+
### MCP Tools
|
|
85
195
|
|
|
86
|
-
|
|
87
|
-
|---------|---------------|
|
|
88
|
-
| **About** | Bio, preferences, goals — the AI's mental model of you |
|
|
89
|
-
| **Soul** | Behavioral instructions for AI — tone, guardrails, priorities |
|
|
90
|
-
| **Areas** | Long-term life/work domains (Health, Finances, Marketing) |
|
|
91
|
-
| **Projects** | Active, time-bound work with goals and deadlines |
|
|
92
|
-
| **Memory** | Bookmarks, links, ideas, notes, reference material |
|
|
196
|
+
6 MCP tools let your AI read and write your brain automatically:
|
|
93
197
|
|
|
94
|
-
|
|
198
|
+
| Tool | Purpose | Rate Limit |
|
|
199
|
+
|------|---------|-----------|
|
|
200
|
+
| `get_context` | Read all 5 context sections | 100/min |
|
|
201
|
+
| `get_section` | Read a specific section | 100/min |
|
|
202
|
+
| `search_brain` | Search across all sections | 100/min |
|
|
203
|
+
| `append_brain` | Append content to a section | 10/min |
|
|
204
|
+
| `update_brain` | AI-powered smart update across sections | 10/min |
|
|
205
|
+
| `prompt_brain` | Natural language command (edit, delete, reorganize) | 10/min |
|
|
95
206
|
|
|
96
|
-
|
|
207
|
+
`get_context`, `get_section`, and `search_brain` are read-only (100 req/min). `update_brain`, `append_brain`, and `prompt_brain` use AI processing (10 req/min).
|
|
97
208
|
|
|
98
|
-
|
|
99
|
-
|------|---------|
|
|
100
|
-
| `get_context` | Read all 5 context sections |
|
|
101
|
-
| `get_section` | Read a specific section |
|
|
102
|
-
| `search_brain` | Search across all sections |
|
|
103
|
-
| `append_brain` | Append content to a section |
|
|
104
|
-
| `update_brain` | AI-powered smart update across sections |
|
|
105
|
-
| `prompt_brain` | Natural language command (edit, delete, reorganize) |
|
|
209
|
+
### Config Sync
|
|
106
210
|
|
|
107
|
-
|
|
211
|
+
Sync your agent config files to the cloud with version history and cross-machine sync:
|
|
108
212
|
|
|
109
|
-
|
|
213
|
+
```bash
|
|
214
|
+
piut sync --install # Guided setup
|
|
215
|
+
piut sync --push # Push local changes
|
|
216
|
+
piut sync --pull # Pull cloud changes
|
|
217
|
+
```
|
|
110
218
|
|
|
111
|
-
|
|
219
|
+
#### Supported files for sync
|
|
112
220
|
|
|
113
|
-
| File | Tool |
|
|
114
|
-
|
|
115
|
-
| `CLAUDE.md` | Claude Code |
|
|
116
|
-
| `AGENTS.md` | Multi-agent |
|
|
117
|
-
| `.cursorrules` | Cursor |
|
|
118
|
-
| `.windsurfrules` | Windsurf |
|
|
119
|
-
| `copilot-instructions.md` | GitHub Copilot |
|
|
120
|
-
| `MEMORY.md` | Claude Code |
|
|
121
|
-
| `SOUL.md` | OpenClaw |
|
|
122
|
-
| `rules/*.md` | Various |
|
|
221
|
+
| File | Tool | Typical location |
|
|
222
|
+
|------|------|-----------------|
|
|
223
|
+
| `CLAUDE.md` | Claude Code | Repo root, .claude/ |
|
|
224
|
+
| `AGENTS.md` | Multi-agent | Repo root |
|
|
225
|
+
| `.cursorrules` | Cursor | Repo root |
|
|
226
|
+
| `.windsurfrules` | Windsurf | Repo root |
|
|
227
|
+
| `copilot-instructions.md` | GitHub Copilot | .github/ |
|
|
228
|
+
| `MEMORY.md` | Claude Code | ~/.claude/ |
|
|
229
|
+
| `SOUL.md` | OpenClaw | ~/.openclaw/workspace/ |
|
|
230
|
+
| `rules/*.md` | Various | .cursor/rules/, .claude/rules/ |
|
|
123
231
|
|
|
124
|
-
|
|
232
|
+
---
|
|
125
233
|
|
|
126
234
|
## Documentation
|
|
127
235
|
|
|
128
236
|
| Document | Description |
|
|
129
237
|
|----------|-------------|
|
|
130
238
|
| [**skill.md**](skill.md) | AI skill file — MCP tools, rate limits, error codes |
|
|
131
|
-
| [**
|
|
132
|
-
| [**API
|
|
133
|
-
| [**Cloud Backup**](https://piut.com/docs#cloud-backup) | Cloud backup setup, commands, and sync workflow |
|
|
239
|
+
| [**piut.com/docs**](https://piut.com/docs) | Interactive docs with setup guides and credential auto-fill |
|
|
240
|
+
| [**API Examples**](https://piut.com/docs#api-examples) | Code examples in cURL, Python, Node.js, Go, and Ruby |
|
|
134
241
|
| [**Rate Limits**](https://piut.com/docs#limits) | Limits by plan, error codes, and response headers |
|
|
135
242
|
|
|
136
|
-
All documentation is maintained at [piut.com/docs](https://piut.com/docs) — the interactive version with credential auto-fill and setup guides.
|
|
137
|
-
|
|
138
243
|
## Links
|
|
139
244
|
|
|
140
245
|
- [piut.com](https://piut.com) — Sign up and manage your context
|
|
141
|
-
- [piut.com/docs](https://piut.com/docs) — Interactive documentation
|
|
246
|
+
- [piut.com/docs](https://piut.com/docs) — Interactive documentation
|
|
142
247
|
- [skill.md (raw)](https://raw.githubusercontent.com/M-Flat-Inc/piut/main/skill.md) — Direct link for AI tool configs
|
|
143
248
|
|
|
144
249
|
## License
|
|
145
250
|
|
|
146
251
|
Copyright (c) 2025 M-Flat Inc. All rights reserved.
|
|
147
252
|
|
|
148
|
-
The documentation in this repository is provided for reference and integration purposes. The
|
|
253
|
+
The documentation in this repository is provided for reference and integration purposes. The pıut service is proprietary software.
|