@sage-protocol/cli 0.7.4 → 0.7.5

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.
Files changed (2) hide show
  1. package/README.md +180 -224
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,308 +1,264 @@
1
1
  # Sage CLI
2
2
 
3
- Fast, scriptable tooling for the Sage Protocol. The CLI wraps the Sage SDK so you can:
4
-
5
- - Connect wallets (Cast, Privy, injected) and manage DAO context
6
- - Propose, queue, and execute governance actions
7
- - Inspect treasury and bond positions
8
- - Upload, pin, and verify library prompts on Sage’s IPFS worker
9
- - Run deterministic test-mode flows for local development
10
-
11
- Full guides live at https://docs.sageprotocol.io.
12
-
13
- ## Install & Run
14
-
15
- ### Global install
3
+ Command-line interface for the Sage Protocol. Create, manage, and publish AI prompt libraries with on-chain governance or as personal collections.
16
4
 
17
5
  ```bash
18
6
  npm i -g @sage-protocol/cli
19
- # or on demand
20
- npx @sage-protocol/cli --help
7
+ sage --help
21
8
  ```
22
9
 
23
- The binary is published as `sage`. Update notifications appear once per day unless you set `SAGE_NO_UPDATE_CHECK=1` (e.g., in CI).
10
+ ## Quick Start
24
11
 
25
- ### Workspace development
12
+ ### Personal Library (No Governance)
26
13
 
27
- Requirements: Node 18+ with Corepack enabled (`corepack enable`). From the repo root:
14
+ Create a wallet-owned library for your prompts without DAO overhead:
28
15
 
29
16
  ```bash
30
- corepack yarn plugin import workspace-tools
31
- corepack yarn workspaces focus -A @sage-protocol/cli
32
- corepack yarn workspace @sage-protocol/cli build
33
- corepack yarn workspace @sage-protocol/cli dev # runs src/index.js with ts-node/register
34
- corepack yarn workspace @sage-protocol/cli test # unit suite
35
- ```
17
+ # 1. Connect your wallet
18
+ sage wallet connect
36
19
 
37
- While iterating, rerun `build` to refresh `dist/` (used by `bin/sage.js`).
20
+ # 2. Create a personal library
21
+ sage library personal create --name "My Prompts"
38
22
 
39
- CI or release automation should execute:
23
+ # 3. Push prompts to your library
24
+ sage library personal push <libraryId> --dir ./prompts
40
25
 
41
- ```bash
42
- corepack enable
43
- corepack yarn install --mode=update-lockfile
44
- corepack yarn workspace @sage-protocol/cli build
26
+ # 4. List your libraries
27
+ sage library personal list
45
28
  ```
46
29
 
47
- ## Guided Onboarding
48
-
49
- `sage wizard` (alias: `sage tutorial`) walks new users through the full workflow:
50
-
51
- 1. Detect or create a wallet (`sage wallet connect` under the hood) with clear guidance when keystore directories are missing.
52
- 2. Configure worker credentials and gateways, reusing the `sage config ipfs` onboarding flow.
53
- 3. Upload a prompt, warm the Sage gateway (`https://ipfs.dev.sageprotocol.io/ipfs`), and record the manifest pointer.
54
- 4. Review governance requirements, stake thresholds, and (optionally) create a SubDAO using the selected template.
30
+ ### DAO Library (With Governance)
55
31
 
56
- Run with `--yes` to accept defaults; interactive prompts appear when a safe default does not exist (for example, selecting a local file to upload).
57
-
58
- ## Quick Start: Prompts & Skills
59
-
60
- The simplified prompt workflow uses four core commands:
32
+ Create a governed library with token-based voting:
61
33
 
62
34
  ```bash
63
- # 1. Initialize project with Claude Code skill
64
- sage init --with-skill
65
-
66
- # 2. Install prompts/skills from the platform
67
- sage install <dao-or-cid> # From a DAO
68
- sage install build-web3 # Bundled skill
69
- sage install github:user/repo # From GitHub
35
+ # 1. Quick setup: scan prompts, upload, create DAO, register
36
+ sage library quickstart --name "My DAO Library" --from-dir ./prompts
70
37
 
71
- # 3. List available prompts
72
- sage prompt list # Local + platform
73
- sage prompt list --local # Local only
74
- sage prompt list --search "web3" # Search platform
75
-
76
- # 4. Sync with your DAO
77
- sage sync # Push local changes
78
- sage sync --pull # Pull from DAO
79
- sage sync --dry-run # Preview changes
38
+ # 2. Or step-by-step:
39
+ sage prompts init # Initialize workspace
40
+ sage prompts new my-prompt # Create a prompt
41
+ sage prompts publish # Upload and propose update
80
42
  ```
81
43
 
82
- ### Claude Code Integration
83
-
84
- After `sage init --with-skill`, your project has:
85
-
86
- ```
87
- .claude/
88
- ├── skills/build-web3/ # Auto-discovered by Claude
89
- │ ├── SKILL.md
90
- │ ├── workflows/
91
- │ └── references/
92
- └── commands/build-web3.md # Manual: /build-web3
93
-
94
- CLAUDE.md # Project instructions
95
- ```
96
-
97
- Claude Code auto-discovers skills in `.claude/skills/`. Use `/build-web3` to manually trigger the workflow.
98
-
99
- ### Installing Platform Prompts
100
-
101
- Install prompts from any DAO or content source:
44
+ ### Install Prompts from Others
102
45
 
103
46
  ```bash
104
- # From a DAO (by address or alias)
47
+ # From a DAO
105
48
  sage install 0x1234...abcd
106
49
  sage install my-library
107
50
 
108
- # From IPFS CID
51
+ # From IPFS
109
52
  sage install QmXyz...
110
53
 
111
54
  # From GitHub
112
- sage install github:sage-protocol/example-prompts
55
+ sage install github:user/repo
113
56
  ```
114
57
 
115
- Skills (with `SKILL.md`) install to `.claude/skills/`. Plain prompts install to `prompts/`.
58
+ ## Command Reference
59
+
60
+ ### Library Management
61
+
62
+ | Command | Description |
63
+ |---------|-------------|
64
+ | `sage library quickstart` | Create library + DAO in one command |
65
+ | `sage library info` | Show library info for a DAO |
66
+ | `sage library fork <source>` | Fork an existing library |
67
+ | `sage library personal create` | Create a personal (wallet-owned) library |
68
+ | `sage library personal list` | List your personal libraries |
69
+ | `sage library personal push` | Push files to a personal library |
70
+ | `sage library personal delete` | Delete a personal library |
71
+
72
+ ### Prompt Workspace
73
+
74
+ | Command | Description |
75
+ |---------|-------------|
76
+ | `sage prompts init` | Initialize a prompt workspace |
77
+ | `sage prompts new <key>` | Create a new prompt/skill |
78
+ | `sage prompts list` | List all prompts in workspace |
79
+ | `sage prompts publish` | Build manifest and propose update |
80
+ | `sage prompts sync` | Sync with on-chain state |
81
+ | `sage prompts import <source>` | Import from GitHub/on-chain |
82
+ | `sage prompts search <query>` | Search prompts |
83
+
84
+ ### Personal Prompts
85
+
86
+ | Command | Description |
87
+ |---------|-------------|
88
+ | `sage personal create` | Create a personal registry |
89
+ | `sage personal publish <key>` | Publish a free prompt |
90
+ | `sage personal list` | List personal prompts |
91
+ | `sage personal premium publish` | Publish paid content |
92
+ | `sage personal premium buy` | Purchase a license |
93
+ | `sage personal premium access` | Decrypt purchased content |
94
+ | `sage personal my-licenses` | View owned licenses |
95
+
96
+ ### Wallet & Config
97
+
98
+ | Command | Description |
99
+ |---------|-------------|
100
+ | `sage wallet connect` | Connect a wallet (Cast, Privy, WalletConnect) |
101
+ | `sage wallet balance` | Show wallet balance |
102
+ | `sage config show` | Show current configuration |
103
+ | `sage config ipfs onboard` | Configure IPFS/pinning |
104
+ | `sage secret set <name>` | Store a secret in keychain |
105
+
106
+ ### Governance
107
+
108
+ | Command | Description |
109
+ |---------|-------------|
110
+ | `sage gov propose` | Create a governance proposal |
111
+ | `sage gov vote <proposalId>` | Vote on a proposal |
112
+ | `sage gov queue <proposalId>` | Queue a passed proposal |
113
+ | `sage gov execute <proposalId>` | Execute a queued proposal |
114
+ | `sage proposals list` | List proposals for current DAO |
115
+
116
+ ## Personal Libraries
117
+
118
+ Personal libraries are wallet-owned collections that don't require DAO governance. They're ideal for:
119
+
120
+ - **Individual creators** who want to publish prompts under their own identity
121
+ - **Quick iteration** without governance delays
122
+ - **Premium content** with on-chain licensing via Lit Protocol
123
+
124
+ ### Create and Manage
116
125
 
117
- ## Configuration
118
-
119
- The CLI now treats `.sage/config.json` (project or XDG) as the primary source of truth; `.env` is still loaded for backward compatibility and for secrets, but most workflow settings live in the profile. `sage init` writes the active profile automatically, and you can tweak values with the config commands below. In CI, set env vars only for tokens or temporary overrides.
120
-
121
- Configuration prefers environment variables, then project profiles (`.sage/` in the repo), then XDG base directories (e.g., `~/.config/sage`). Key commands:
122
-
123
- - `sage config profile list` – discover active profiles
124
- - `sage config ipfs onboard` / `sage ipfs setup` – worker & gateway wizard
125
- - `sage config set-rpc <rpcUrl> [--chain-id <id>]` – persist network endpoints per profile
126
- - `sage config addresses set <KEY>=<0x...>` – store contract addresses without touching `.env`
127
- - `sage config show --all` – inspect the merged view
128
-
129
- Override the keystore directory with `SAGE_CAST_KEYSTORE_DIR` or use the defaults (`~/.foundry/keystores`, project `.cast-keystore`).
126
+ ```bash
127
+ # Create a new personal library
128
+ sage library personal create --name "My AI Prompts" --description "Curated prompts for development"
130
129
 
131
- ### Secrets
130
+ # View your libraries
131
+ sage library personal list
132
132
 
133
- By default the CLI stores sensitive values (e.g., `PINATA_JWT`, worker tokens) in your OS keychain using keytar and writes only references into `.sage/config.json`.
133
+ # Push content from a directory
134
+ sage library personal push lib_abc123 --dir ./my-prompts
134
135
 
135
- - Set: `sage secret set pinata.jwt` (prompts) or `sage config ipfs set-pinata --jwt <token>`
136
- - Get (masked): `sage secret get pinata.jwt`
137
- - Delete/list: `sage secret delete <name>`, `sage secret list`
136
+ # Get library details
137
+ sage library personal info lib_abc123
138
138
 
139
- In CI set `SAGE_SECRETS_BACKEND=env` and provide env vars like `SAGE_SECRET_PINATA_JWT` or the original provider variables; the CLI will resolve them without touching the keychain. Use `--allow-plain-secret` on `config ipfs set-*` only if you truly need to persist secrets in plaintext.
139
+ # Delete a library
140
+ sage library personal delete lib_abc123
141
+ ```
140
142
 
141
- ## IPFS & Pinning
143
+ ### Premium Content
142
144
 
143
- Uploading defaults to the Sage worker provider with the hosted gateway:
145
+ Sell encrypted prompts with on-chain licensing:
144
146
 
145
- - Provider: `worker`
146
- - Gateway: `https://ipfs.dev.sageprotocol.io/ipfs`
147
- - Worker base: `https://api.sageprotocol.io`
147
+ ```bash
148
+ # Publish premium content (encrypted via Lit Protocol)
149
+ sage personal premium publish my-prompt \
150
+ --file prompts/valuable-prompt.md \
151
+ --price 100 \
152
+ --name "Advanced Prompt" \
153
+ --description "High-value prompt template"
148
154
 
149
- Pinata is now opt-in. Use `--use-pinata` (or set `SAGE_IPFS_PROVIDER=pinata`) when you want to supply Pinata credentials; otherwise the worker handles warming and pinning. Additional options:
155
+ # Check pricing
156
+ sage personal premium price <creator> <key>
150
157
 
151
- - `--warm` or `SAGE_IPFS_WARM=true` to prefetch via the gateway
152
- - `--provider <worker|pinata|w3s>` to switch providers per command
153
- - `sage ipfs pin <cid>` to ensure content stays replicated after upload
158
+ # Buy a license
159
+ sage personal premium buy <creator> <key> --auto-approve
154
160
 
155
- The CLI signs worker challenges with your connected wallet, so make sure your signer has the proper on-chain roles. Configure timeouts with `SAGE_IPFS_TIMEOUT_MS` and retry behaviour with `SAGE_IPFS_RETRIES`.
161
+ # Access purchased content
162
+ sage personal premium access <creator> <key> --out decrypted.md
156
163
 
157
- ### Off‑chain credits (Phase A)
164
+ # View your licenses
165
+ sage personal my-licenses
166
+ ```
158
167
 
159
- - Enable `SAGE_PAY_TO_PIN: true` in your profile flags to surface credits UX.
160
- - Show credits: `sage ipfs credits --worker-url https://ipfs.dev.sageprotocol.io`
161
- - Buy credits: `sage ipfs buy-credits --worker-url …` (prints checkout URL)
162
- - Pin with credits: `sage ipfs pin <cid> --worker-url …` (prints 402 guidance when needed). You can always use your own provider with `sage ipfs upload --provider pinata` if you prefer BYO model.
168
+ ## IPFS & Pinning
163
169
 
164
- ### Prepare‑only auctions (LaunchGate + Safe)
170
+ The CLI uses the Sage IPFS worker by default:
165
171
 
166
- - We do not broadcast Doppler auction creation from local EOAs. Instead:
167
- - Set profile flags: `SAGE_DOPPLER_PERMITTED: true` and optionally `SAGE_DOPPLER_ALPHA: true` (unified SDK).
168
- - Run: `sage doppler create --prepare-only --variant dynamic [--via-wrapper] --output safe-payload.json`.
169
- - To forbid direct deploy/migrate, set `SAGE_REQUIRE_LAUNCHGATE: true`.
172
+ - **Gateway**: `https://ipfs.dev.sageprotocol.io/ipfs`
173
+ - **Worker**: `https://api.sageprotocol.io`
170
174
 
171
- ### On‑chain pin and credits (Phase B)
175
+ ```bash
176
+ # Configure IPFS
177
+ sage config ipfs onboard
172
178
 
173
- - Pin burn (prepare-only vs send):
174
- - Prepare: `SAGE_PAY_TO_PIN=1 SAGE_PAY_TO_PIN_MODE=onchain sage ipfs pin <cid>`
175
- - Send: `… sage ipfs pin <cid> --send` (requires wallet configured)
176
- - Buy credits on-chain:
177
- - Prepare (simple allowance): `sage ipfs buy-credits-onchain --token <USDC> --amount <baseUnits> --credits <n>`
178
- - Prepare (Permit2): `sage ipfs buy-credits-onchain --permit2 <addr> --token <USDC> --amount <baseUnits> --credits <n>`
179
- - Append `--send` to submit the transaction directly.
179
+ # Upload content
180
+ sage ipfs upload ./my-file.md
180
181
 
181
- ### Signed Addresses Payload (Worker Implementers)
182
+ # Pin existing content
183
+ sage ipfs pin <cid>
182
184
 
183
- - Schema: the Worker should serve a JSON with this shape under `/addresses`:
184
- ```json
185
- {
186
- "payload": {
187
- "chainId": 84532,
188
- "signer": "0xTreasurySafeOrSigner",
189
- "registry": "0xAddressRegistryOrNull",
190
- "addresses": { "PAYMENT_ROUTER_ADDRESS": "0x...", "CREDIT_TOKEN_ADDRESS": "0x..." },
191
- "expected": { "PAYMENT_ROUTER_ADDRESS": "0xcodehash", "CREDIT_TOKEN_ADDRESS": "0xcodehash" },
192
- "effectiveFromBlock": 1234567,
193
- "timestamp": 1730000000,
194
- "expiresAt": 1730864000
195
- },
196
- "signature": "0x…"
197
- }
198
- ```
199
- - The signature must be produced by the allowed signer:
200
- - EOA: `ethers.signMessage(stableStringify(payload))` and publish the signer in `SAGE_TRUSTED_SIGNER` (CLI env or profile flag), or
201
- - Safe (contract): sign via a Safe module; the CLI can verify using EIP‑1271 `isValidSignature` against `payload.signer`.
202
- - Validation in CLI:
203
- - `sage config addresses verify --worker https://worker/addresses` (reads payload, verifies signature, checks codehashes on-chain).
204
- - `sage config addresses fetch --worker … --write` (same as verify, then writes addresses to profile).
185
+ # Check credits
186
+ sage ipfs credits
187
+ ```
205
188
 
206
- ## Premium Prompts
189
+ ### Credits
207
190
 
208
- Personal premium prompts let creators sell encrypted content with on-chain licensing via Lit Protocol. Buyers pay in SXXX (the Sage Protocol token) and receive a decryption license.
191
+ ```bash
192
+ # Show credit balance
193
+ sage ipfs credits
209
194
 
210
- ### Publish premium content
195
+ # Buy credits (opens checkout)
196
+ sage ipfs buy-credits
211
197
 
212
- ```bash
213
- sage personal premium publish my-prompt \
214
- --file prompts/my-prompt.md \
215
- --price 100 \
216
- --name "My Premium Prompt" \
217
- --description "A valuable prompt template"
198
+ # Pin with credits
199
+ sage ipfs pin <cid>
218
200
  ```
219
201
 
220
- Options:
221
- - `--price <sxxx>` — Price in SXXX tokens (required)
222
- - `--file <path>` — Content file to encrypt and publish (required)
223
- - `--name <name>` — Display name for the listing
224
- - `--description <text>` — Description shown to buyers
225
- - `--skip-registry` — Skip on-chain registry (marketplace only)
202
+ ## Configuration
226
203
 
227
- ### Check price and fees
204
+ Configuration is stored in `.sage/config.json` (project) or `~/.config/sage` (global).
228
205
 
229
206
  ```bash
230
- sage personal premium price <creator> <key>
231
- ```
232
-
233
- Shows the current price, platform fee breakdown, and creator payout.
207
+ # Show all config
208
+ sage config show --all
234
209
 
235
- ### Buy a license
210
+ # Set RPC endpoint
211
+ sage config set-rpc https://base-sepolia.publicnode.com --chain-id 84532
236
212
 
237
- ```bash
238
- sage personal premium buy <creator> <key> [expectedPrice] \
239
- --auto-approve \
240
- --max-price 150
213
+ # Manage profiles
214
+ sage config profile list
215
+ sage config profile use <name>
241
216
  ```
242
217
 
243
- Options:
244
- - `--max-price <sxxx>` — Maximum price you're willing to pay
245
- - `--auto-approve` — Automatically approve SXXX allowance
246
- - `--deadline <seconds>` — Transaction deadline window (default: 600)
218
+ ### Secrets
247
219
 
248
- ### Access purchased content
220
+ Secrets are stored in your OS keychain:
249
221
 
250
222
  ```bash
251
- sage personal premium access <creator> <key> --out decrypted.md
223
+ sage secret set pinata.jwt
224
+ sage secret get pinata.jwt
225
+ sage secret list
226
+ sage secret delete <name>
252
227
  ```
253
228
 
254
- Decrypts and displays (or saves) content you've licensed. Requires a valid on-chain license.
229
+ In CI, set `SAGE_SECRETS_BACKEND=env` and use environment variables.
255
230
 
256
- Options:
257
- - `--out <file>` — Save decrypted content to file
258
- - `--skip-decrypt` — Check license status without decrypting
231
+ ## Claude Code Integration
259
232
 
260
- ### View your licenses
233
+ Initialize a project with Claude Code skill support:
261
234
 
262
235
  ```bash
263
- sage personal my-licenses --json
236
+ sage init --with-skill
264
237
  ```
265
238
 
266
- Lists all premium content licenses owned by your wallet.
267
-
268
- ### Unlist content
269
-
270
- ```bash
271
- sage personal premium unlist <key>
239
+ This creates:
272
240
  ```
241
+ .claude/
242
+ ├── skills/build-web3/
243
+ │ ├── SKILL.md
244
+ │ └── workflows/
245
+ └── commands/build-web3.md
273
246
 
274
- Removes your listing from the marketplace (sets price to 0). Existing license holders retain access.
275
-
276
- ## Testing
247
+ CLAUDE.md
248
+ ```
277
249
 
278
- Unit suites live under `packages/cli/tests`. Run `corepack yarn workspace @sage-protocol/cli test:unit` for fast feedback or `test:ci` for coverage reports. Some wallet tests mock Foundry; ensure `cast` is available on your PATH when running the full suite.
250
+ Import skills from the platform:
279
251
 
280
- ## Contributing
252
+ ```bash
253
+ sage prompts import-skill <name>
254
+ sage install build-web3
255
+ ```
281
256
 
282
- - Fork, branch, and focus-install dependencies (`yarn workspaces focus -A @sage-protocol/cli`).
283
- - Add or update tests alongside code changes.
284
- - Keep UX messages explicit—surface actionable guidance when commands fail.
285
- - Submit a PR with context, testing performed, and any follow-up work required.
257
+ ## Documentation
286
258
 
287
- See `CONTRIBUTING.md` for full guidelines.
259
+ - [Development Guide](docs/DEVELOPMENT.md) - Setup, testing, and contributing
260
+ - [Full Docs](https://docs.sageprotocol.io) - Complete documentation
288
261
 
289
262
  ## License
290
263
 
291
- Apache 2.0 — see `LICENSE` in this directory.
292
- ### Feature flags and environment gating
293
-
294
- - Production defaults avoid environment variables. Use profile-based flags in `.sage/config.json` under the active profile.
295
- - Supported flags (profile `profiles.<name>.flags`):
296
- - `SAGE_CLI_TEST_MODE`: enables test-mode helpers and allows environment overrides for rapid iteration.
297
- - `SAGE_FLAGS_ALLOW_ENV`: allows reading feature flags and network settings from `process.env`.
298
- - `SAGE_LEGACY_ENV_MIRROR`: mirrors profile settings into `process.env` (legacy behavior). Disabled by default.
299
-
300
- Notes
301
- - `resolveFlag(name)` now consults profile flags first; env is only used in test mode or when `SAGE_FLAGS_ALLOW_ENV=1`.
302
- - `resolveRpcUrl()` and `resolveChainId()` prefer profile values; env is only used when `SAGE_FLAGS_ALLOW_ENV` or test mode is enabled.
303
- - Profile presets
304
- - Seed example presets for Base or Mainnet using the helper script:
305
- - `node packages/cli/scripts/presets/seed-profiles.js --address_registry_address 0x... --payment_router_address 0x... --credit_token_address 0x...`
306
- - Outputs JSON under `packages/cli/assets/presets/<name>.json` (set `PRESET_NAME=base` or `PRESET_NAME=mainnet`).
307
- - Import into the active profile:
308
- - `sage config addresses import --file packages/cli/assets/presets/base.json`
264
+ Apache 2.0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sage-protocol/cli",
3
- "version": "0.7.4",
3
+ "version": "0.7.5",
4
4
  "description": "Sage Protocol CLI for managing AI prompt libraries",
5
5
  "bin": {
6
6
  "sage": "./bin/sage.js"