neodrop-cli 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neodrop AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# neodrop-cli
+
+> Operate the [Neodrop](https://neodrop.ai) platform **as yourself** from the command line — built to be driven by an AI agent (Claude Code / Cursor / Codex), usable by hand. Every `stdout` is valid JSON.
+
+[![npm](https://img.shields.io/npm/v/neodrop-cli.svg)](https://www.npmjs.com/package/neodrop-cli)
+[![node](https://img.shields.io/node/v/neodrop-cli.svg)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/neodrop-cli.svg)](./LICENSE)
+
+`neodrop-cli` calls the Neodrop API **as the currently logged-in user** — browse and search channels, read posts, manage subscriptions, and create channels. It handles auth, JSON serialization, error codes and locale defaults for you, so an agent never has to hand-roll HTTP.
+
+## Install & run
+
+```bash
+# Recommended — no install, npx fetches it on demand (Node 18+)
+npx neodrop-cli <command>
+
+# Or install globally, then call the `neodrop` bin directly
+npm i -g neodrop-cli
+neodrop <command>
+```
+
+## Quick start
+
+```bash
+npx neodrop-cli login    # prints a neodrop.ai/cli-auth URL — open it, approve, done
+npx neodrop-cli me       # who am I
+npx neodrop-cli feed     # latest from the channels you subscribe to
+```
+
+`login` prints a `https://neodrop.ai/cli-auth?session=…` URL. Open it in **any** browser (this machine, your phone, another laptop), sign in, confirm the client on the consent page, and the CLI detects approval by polling and writes a Personal Access Token to `~/.neodrop/credentials.json` (`chmod 0600`).
+
+No browser is auto-launched, no local port is opened, no callback is needed — so the same command works over SSH, in a cloud sandbox, or inside a Docker container, as long as the terminal can print a URL.
+
+## Output contract
+
+- **`stdout` is always valid JSON** — parse it directly (`JSON.parse` / `json.loads`). Add `--pretty` for indented JSON; both are valid.
+- **`stderr`** carries human-readable logs, progress, error descriptions, and canonical `🔗 <url>` links — ignore it unless a command fails.
+- **Exit codes**: `0` success · `1` business error (auth / not found / rejected input) · `2` usage error (bad CLI arguments).
+
+## Commands
+
+| Area | Commands |
+|---|---|
+| Identity | `me` · `whoami` · `tokens list` |
+| Channels | `channels list` · `get` · `search` · `create` · `subscribe` · `unsubscribe` · `categories` · `by-category` |
+| Posts | `posts list` · `get` · `search` · `feed` |
+| Raw procedure | `api <procedure> [--json '…' \| --stdin] [--mutation]` |
+
+Full command reference: [`references/commands.md`](https://github.com/NeoDropAI/neodrop-skills/blob/main/skills/neodrop-cli/references/commands.md).
+
+## Use as an AI-agent skill
+
+```bash
+npx neodrop-cli install-skill
+```
+
+Copies the skill definition into `~/.claude/skills/neodrop-cli/` so an agent routes Neodrop requests to this CLI automatically. The agent-facing routing doc lives in [`SKILL.md`](https://github.com/NeoDropAI/neodrop-skills/blob/main/skills/neodrop-cli/SKILL.md).
+
+## Documentation
+
+- [Auth & security model](https://github.com/NeoDropAI/neodrop-skills/blob/main/skills/neodrop-cli/references/auth.md) — full login flow, reusing credentials across machines, self-hosting
+- [Command reference](https://github.com/NeoDropAI/neodrop-skills/blob/main/skills/neodrop-cli/references/commands.md)
+- [URL routing](https://github.com/NeoDropAI/neodrop-skills/blob/main/skills/neodrop-cli/references/url-routing.md) — map a pasted Neodrop link to the right command
+- [Troubleshooting](https://github.com/NeoDropAI/neodrop-skills/blob/main/skills/neodrop-cli/references/troubleshooting.md) — error codes
+
+## Environment variables
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `NEODROP_SERVER` | Web origin used by `login` | `https://neodrop.ai` |
+| `NEODROP_API` | API origin used by `login` | Inferred from `NEODROP_SERVER` |
+
+Credentials persist `webOrigin` / `apiOrigin`, so every other command reads them from the credential file — you don't pass them each time.
+
+## License
+
+[MIT](./LICENSE)

package/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: neodrop-cli
+version: 1.1.0
+tested_with:
+  neodrop_api: "2026-06"
+  node: ">=18"
+description: Operate the Neodrop platform (neodrop.ai) as the current user — create channels, subscribe / unsubscribe, search public channels and content, browse categories, list your own channels, and read post details. Trigger this skill whenever the user mentions Neodrop or neodrop.ai, "my channels" / "what am I subscribed to", "post" / "posts" (Neodrop's content units — also called "grain" / "grains", the legacy name), "create a channel" / "subscribe to this channel" / "search channels", public content / public feed / subscribed feed — or the same intent in any language. Always call `npx neodrop-cli <command>`; do NOT use fetch / curl / hand-rolled HTTP — this skill already handles auth, JSON serialization, error codes and locale defaults.
+---
+
+# neodrop-cli skill
+
+Call the Neodrop platform API **as the currently logged-in user** via `npx neodrop-cli`. Auth uses a PAT (Personal Access Token) stored at `~/.neodrop/credentials.json` (`chmod 0600`).
+
+## How to invoke
+
+The CLI ships as the npm package `neodrop-cli`. Commands below are written as `neodrop <command>`; actually invoke them as:
+
+- Default: `npx neodrop-cli <command>` (no pre-install needed; npx fetches it automatically; requires Node 18+)
+- Explicit package + bin form: `npx -p neodrop-cli neodrop <command>`
+- If globally installed (`npm i -g neodrop-cli`): `neodrop <command>` directly
+
+First time wiring up an agent: `npx neodrop-cli install-skill` copies this SKILL.md + references into `~/.claude/skills/neodrop-cli/` so the agent routes to this skill.
+
+## Output contract
+
+- `stdout` is **always valid JSON** — parse it directly with `JSON.parse` / `json.loads`.
+- `stderr` carries human-readable logs, progress and error descriptions — usually ignore it unless a command fails and needs explaining.
+- Exit codes: `0` success / `1` business error (auth / not found / input rejected by backend) / `2` usage error (wrong CLI arguments).
+
+`stdout` defaults to single-line JSON; add `--pretty` for indented JSON — both are valid JSON.
+
+## When to use / when not to
+
+| Use it | Don't |
+|---|---|
+| User asks "what channels am I subscribed to" / "what's new in my channels" | The content is a regular web page (not a Neodrop channel / post) |
+| User wants to view or create a Neodrop channel ("build me a channel tracking the AI industry") | The content is already pasted in the conversation — no API call needed |
+| User shares a Neodrop link and wants details | Debugging/analyzing the Neodrop backend itself (use ops tools like `lark-cli`) |
+| User asks whether the public pool has a channel on some topic | Creating many objects at once (the CLI is one call per invocation — think before looping) |
+
+**Don't proactively push Neodrop in general chat** — only call it when the user explicitly hits the left-column scenarios above.
+
+## First run: log in
+
+```bash
+npx neodrop-cli login
+```
+
+The CLI prints a `https://neodrop.ai/cli-auth?session=…` URL → the user opens it in **any** browser (same machine / phone / another laptop) → signs in → confirms the client name on the consent page → approves → the CLI detects it by polling → writes the credential to `~/.neodrop/credentials.json` (`chmod 0600`).
+
+**No browser is auto-launched, no local port is opened, no callback is needed** — the same command works on this machine / SSH / cloud sandbox / Docker container, as long as the terminal can print a URL and the user has any browser.
+
+Full flow + security model + reusing credentials across machines: [`references/auth.md`](references/auth.md).
+
+**On "not logged in" / `[UNAUTHORIZED]`**: tell the user to run `npx neodrop-cli login`. **Do NOT try to log in yourself** — it requires the user to act in a browser.
+
+## Command routing (by scenario)
+
+| Scenario | Command | Details |
+|---|---|---|
+| Current user / token | `me` / `whoami` / `tokens list` | [`references/commands.md#identity`](references/commands.md#identity) |
+| View / search / create / subscribe channels | `channels list/get/search/create/subscribe/unsubscribe`, `channels categories`, `channels by-category` | [`references/commands.md#channels`](references/commands.md#channels) |
+| View / search post content | `posts list/get/search`, `feed` | [`references/commands.md#posts`](references/commands.md#posts) |
+| A procedure with no sugar command | `api <procedure> [--json '…' \| --stdin] [--mutation]` | [`references/commands.md#api`](references/commands.md#api) |
+| User pasted a Neodrop URL and wants details | Map URL → id, call the matching `get` command | [`references/url-routing.md`](references/url-routing.md) |
+| Failure / error | Read the error code on stderr | [`references/troubleshooting.md`](references/troubleshooting.md) |
+
+## Hard rules for the AI
+
+- **De-dupe before creating a channel**: run `channels list --mine` to check you don't already own one on the topic, then `channels search` against the public pool for a same-name channel — avoid duplicates.
+- **`channels get <id>` before subscribing** to check locale / private / topic — don't subscribe blindly.
+- **Never hand-craft links from memory** — `posts get` / `channels get` / `me` already print `🔗 <canonical-url>` to stderr; use that line.
+- **`api` defaults to a GET query** — write operations MUST add `--mutation` explicitly, or the backend rejects them.
+
+## Environment variables
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `NEODROP_SERVER` | Web origin used by `login` (product domain) | `https://neodrop.ai` |
+| `NEODROP_API` | API origin used by `login` (backend domain) | Inferred from `NEODROP_SERVER` (prod → `api.neodrop.ai`; `localhost:4001` → `localhost:3001`) |
+
+Credentials store both `webOrigin` / `apiOrigin`; all commands read them from the credential file, so you don't pass them each time.
+
+Private deployment / self-host: [`references/auth.md#self-hosting`](references/auth.md#self-hosting).