jotbird 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JotBird LLC
+
+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,94 @@
+# JotBird
+
+Publish Markdown from the command line. Three commands to go from file to shareable link.
+
+```
+$ jotbird publish README.md
+Published: https://share.jotbird.com/bright-calm-meadow
+```
+
+Every published page gets a responsive URL — no ads, no tracking, no clutter, just your content. Unlike gists, pastebins, and wikis, JotBird links are readable, unlisted, and designed to be shared — not browsed. Noindex by default.
+
+## Install
+
+Requires Node.js 18+.
+
+```bash
+npm install -g jotbird
+```
+
+## Quick start
+
+```bash
+# 1. Log in (one-time setup)
+jotbird login
+
+# 2. Publish a file
+jotbird publish notes.md
+
+# 3. Update it — same URL, fresh content
+jotbird publish notes.md
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `jotbird login` | Authenticate with your JotBird account |
+| `jotbird publish <file>` | Publish or update a Markdown file |
+| `jotbird publish` | Read Markdown from stdin |
+| `jotbird list` | List your published documents (also visible in the [web app](https://www.jotbird.com/app) as read-only) |
+| `jotbird unpublish <file\|slug>` | Take down the public URL (keeps document in account) |
+| `jotbird remove <file\|slug>` | Permanently delete a document |
+| `jotbird help` | Show help |
+
+## How it works
+
+The CLI tracks file-to-slug mappings in a `.jotbird` file in your working directory. When you publish the same file again, it updates the existing document at the same URL.
+
+```bash
+$ jotbird publish README.md
+Published: https://share.jotbird.com/bright-calm-meadow
+
+$ jotbird publish README.md
+Updated: https://share.jotbird.com/bright-calm-meadow
+```
+
+Pipe from stdin for scripts and CI:
+
+```bash
+cat notes.md | jotbird publish
+echo "# Hello" | jotbird publish
+```
+
+When publishing from stdin, no file mapping is created — each publish creates a new document.
+
+## Authentication
+
+Run `jotbird login` to open your browser and authenticate. The CLI will automatically receive your API key once you sign in — no copy-pasting required. If the browser doesn't open, the CLI displays a URL to visit manually and falls back to a paste prompt.
+
+The key is stored locally at `~/.config/jotbird/credentials` with `0600` permissions.
+
+## Image uploads
+
+Image uploads are not supported. Markdown image references (e.g. `![alt](url)`) will render only if they point to externally-hosted images.
+
+## Free vs Pro
+
+| | Free | Pro |
+|---|---|---|
+| Published links | 90 days expiration | Permanent |
+| Active documents | 10 | Unlimited |
+| Rate limit | 10 publishes/hour | 100 publishes/hour |
+
+Upgrade at [jotbird.com/pro](https://www.jotbird.com/pro).
+
+## Links
+
+- [JotBird](https://www.jotbird.com/)
+- [CLI docs](https://www.jotbird.com/cli)
+- [API docs](https://www.jotbird.com/docs/api)
+
+## License
+
+MIT

package/dist/api.js

@@ -0,0 +1,91 @@
+import { getApiKey, API_BASE } from "./config.js";
+
+/**
+ * Make an authenticated API request to the JotBird CLI API.
+ */
+async function apiRequest(path, body = null) {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    throw new Error("Not logged in. Run `jotbird login` first.");
+  }
+
+  const resp = await fetch(`${API_BASE}${path}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: body ? JSON.stringify(body) : "{}",
+  });
+
+  const data = await resp.json().catch(() => null);
+
+  if (!resp.ok) {
+    const msg = data?.error || `HTTP ${resp.status}`;
+    throw new Error(msg);
+  }
+
+  return data;
+}
+
+/**
+ * Publish or update a document.
+ */
+export async function publish({ markdown, title, slug }) {
+  const body = { markdown };
+  if (title) body.title = title;
+  if (slug) body.slug = slug;
+  return apiRequest("/api/v1/publish", body);
+}
+
+/**
+ * List all published documents.
+ */
+export async function listDocuments() {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    throw new Error("Not logged in. Run `jotbird login` first.");
+  }
+
+  const resp = await fetch(`${API_BASE}/api/v1/documents`, {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+    },
+  });
+
+  const data = await resp.json().catch(() => null);
+
+  if (!resp.ok) {
+    const msg = data?.error || `HTTP ${resp.status}`;
+    throw new Error(msg);
+  }
+
+  return data;
+}
+
+/**
+ * Permanently remove a document (deletes from database and public URL).
+ */
+export async function removeDocument(slug) {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    throw new Error("Not logged in. Run `jotbird login` first.");
+  }
+
+  const resp = await fetch(`${API_BASE}/api/v1/documents?slug=${encodeURIComponent(slug)}`, {
+    method: "DELETE",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+    },
+  });
+
+  const data = await resp.json().catch(() => null);
+
+  if (!resp.ok) {
+    const msg = data?.error || `HTTP ${resp.status}`;
+    throw new Error(msg);
+  }
+
+  return data;
+}

package/dist/cli.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { createInterface } from "node:readline";
+import { getApiKey, saveApiKey, getCredentialsPath, API_BASE } from "./config.js";
+import { publish, listDocuments, removeDocument } from "./api.js";
+import { readMappings, setMapping, removeMapping } from "./mapping.js";
+import { startCallbackServer, openBrowser } from "./login.js";
+import { ALLOWED_EXTENSIONS, isAllowedFile } from "./files.js";
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+async function main() {
+  switch (command) {
+    case "login":
+      return cmdLogin();
+    case "publish":
+      return cmdPublish(args.slice(1));
+    case "remove":
+      return cmdRemove(args.slice(1));
+    case "list":
+      return cmdList();
+    case "help":
+    case "--help":
+    case "-h":
+      return cmdHelp();
+    case "version":
+    case "--version":
+    case "-v":
+      return cmdVersion();
+    default:
+      if (!command) {
+        cmdHelp();
+        process.exit(1);
+      }
+      console.error(`Unknown command: ${command}`);
+      console.error('Run "jotbird help" for usage.');
+      process.exit(1);
+  }
+}
+
+// ---- Commands ----
+
+async function cmdLogin() {
+  const existing = getApiKey();
+  if (existing) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => {
+      rl.question("You are already logged in. Replace existing token? [y/N] ", resolve);
+    });
+    rl.close();
+    if (answer.toLowerCase() !== "y") {
+      console.log("Cancelled.");
+      return;
+    }
+  }
+
+  // Try to start a local callback server for automatic token capture
+  let server = null;
+  try {
+    server = await startCallbackServer();
+  } catch {
+    // Fall through to manual flow
+  }
+
+  const baseUrl = `${API_BASE}/account/api-key`;
+  const loginUrl = server
+    ? `${baseUrl}?callback=${encodeURIComponent(`http://127.0.0.1:${server.port}/callback`)}`
+    : baseUrl;
+
+  const opened = await openBrowser(loginUrl);
+
+  if (server) {
+    if (opened) {
+      console.log("\nOpening browser to log in...");
+    } else {
+      console.log("\nTo log in, open this URL in your browser:\n");
+      console.log(`  ${loginUrl}`);
+    }
+    console.log("\nWaiting for browser authentication...");
+    console.log("Or paste your API token here and press Enter:\n");
+
+    // Race: callback server vs manual paste — first one wins
+    const rl2 = createInterface({ input: process.stdin, output: process.stdout });
+    const manualPromise = new Promise((resolve) => {
+      rl2.question("> ", (answer) => resolve(answer.trim()));
+    });
+
+    let token = null;
+    try {
+      token = await Promise.race([
+        server.tokenPromise,
+        manualPromise,
+      ]);
+    } catch {
+      // Timeout — fall through
+    } finally {
+      rl2.close();
+      server.close();
+    }
+
+    if (token && token.startsWith("jb_")) {
+      saveApiKey(token);
+      console.log(`\n✓ Logged in! Token saved to ${getCredentialsPath()}`);
+      return;
+    }
+
+    if (token) {
+      console.error("\nInvalid token format. Token should start with jb_");
+      process.exit(1);
+    }
+
+    console.log("\nLogin timed out. Please try again.");
+    process.exit(1);
+  } else {
+    console.log("\nTo log in, generate an API token in your browser:\n");
+    console.log(`  ${loginUrl}\n`);
+    console.log("Sign in if needed, then copy the token shown on the page.\n");
+  }
+
+  // Manual fallback (only when callback server couldn't start)
+  const rl2 = createInterface({ input: process.stdin, output: process.stdout });
+  const manualToken = await new Promise((resolve) => {
+    rl2.question("Paste your API token: ", resolve);
+  });
+  rl2.close();
+
+  const trimmed = manualToken.trim();
+  if (!trimmed.startsWith("jb_")) {
+    console.error("Invalid token format. Token should start with jb_");
+    process.exit(1);
+  }
+
+  saveApiKey(trimmed);
+  console.log(`\n✓ Logged in! Token saved to ${getCredentialsPath()}`);
+}
+
+async function cmdPublish(fileArgs) {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    console.error("✗ Not logged in. Run `jotbird login` first.");
+    process.exit(1);
+  }
+
+  let markdown;
+  let filename = null;
+
+  if (fileArgs.length === 0 || fileArgs[0] === "-") {
+    // Read from stdin
+    markdown = await readStdin();
+    if (!markdown.trim()) {
+      console.error("✗ No input received from stdin.");
+      process.exit(1);
+    }
+  } else {
+    filename = fileArgs[0];
+
+    if (!isAllowedFile(filename)) {
+      const extensions = [...ALLOWED_EXTENSIONS].join(", ");
+      console.error(`✗ Unsupported file type. Allowed extensions: ${extensions}`);
+      process.exit(1);
+    }
+
+    try {
+      markdown = readFileSync(filename, "utf-8");
+    } catch (err) {
+      console.error(`✗ Cannot read file: ${filename}`);
+      process.exit(1);
+    }
+  }
+
+  // Check for existing mapping
+  let slug = null;
+  if (filename) {
+    const mappings = readMappings();
+    slug = mappings.get(filename) || mappings.get(basename(filename)) || null;
+  }
+
+  try {
+    let result;
+    try {
+      result = await publish({ markdown, slug });
+    } catch (err) {
+      // If the slug was not found, drop the stale mapping and retry as new
+      if (slug && err.message && err.message.includes("not found")) {
+        console.error(`  Slug "${slug}" no longer exists — publishing as new document.`);
+        if (filename) removeMapping(filename);
+        result = await publish({ markdown, slug: null });
+      } else {
+        throw err;
+      }
+    }
+
+    if (filename) {
+      setMapping(filename, result.slug);
+    }
+
+    if (result.created) {
+      console.log(`\n✨ Published → ${result.url}`);
+    } else {
+      console.log(`\n✓ Updated → ${result.url}`);
+    }
+
+    if (result.expiresAt) {
+      const date = new Date(result.expiresAt);
+      console.log(`  Expires ${date.toLocaleDateString()}`);
+    }
+  } catch (err) {
+    console.error(`\n✗ Publish failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+async function cmdRemove(removeArgs) {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    console.error("✗ Not logged in. Run `jotbird login` first.");
+    process.exit(1);
+  }
+
+  if (removeArgs.length === 0) {
+    console.error("Usage: jotbird remove <file.md|slug>");
+    process.exit(1);
+  }
+
+  const target = removeArgs[0];
+
+  // Resolve slug: check .jotbird mapping first, otherwise treat as slug directly
+  const mappings = readMappings();
+  const slug = mappings.get(target) || mappings.get(basename(target)) || target;
+
+  try {
+    await removeDocument(slug);
+    removeMapping(target);
+    console.log(`\n✓ Removed ${slug}`);
+  } catch (err) {
+    console.error(`\n✗ Remove failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+async function cmdList() {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    console.error("✗ Not logged in. Run `jotbird login` first.");
+    process.exit(1);
+  }
+
+  try {
+    const result = await listDocuments();
+    const docs = result.documents || [];
+
+    if (docs.length === 0) {
+      console.log("No published documents yet.");
+      return;
+    }
+
+    console.log("");
+    for (const doc of docs) {
+      const title = doc.title || "(untitled)";
+      const source = doc.source === "api" || doc.source === "cli" ? " [api]" : "";
+      console.log(`  ${doc.slug}  ${title}${source}`);
+      console.log(`    ${doc.url}`);
+    }
+
+    console.log(`\n  ${docs.length} document${docs.length === 1 ? "" : "s"}`);
+  } catch (err) {
+    console.error(`\n✗ Failed to list documents: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+function cmdHelp() {
+  console.log(`
+jotbird - Publish Markdown from the command line
+
+Usage:
+  jotbird login                    Authenticate with JotBird
+  jotbird publish <file.md>        Publish or update a Markdown/text file
+  jotbird publish                  Read Markdown from stdin
+  jotbird remove <file.md|slug>    Permanently delete a document
+  jotbird list                     List your published documents
+  jotbird help                     Show this help message
+
+Examples:
+  jotbird publish README.md
+  cat notes.md | jotbird publish
+  echo "# Hello" | jotbird publish
+  jotbird remove my-old-post
+
+Files are tracked via a .jotbird mapping file in the current directory.
+If a mapping exists, publish updates the existing URL.
+`.trim());
+}
+
+function cmdVersion() {
+  console.log("jotbird 0.1.0");
+}
+
+// ---- Helpers ----
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", (chunk) => { data += chunk; });
+    process.stdin.on("end", () => resolve(data));
+
+    // If stdin is a TTY (no pipe), show a hint and wait
+    if (process.stdin.isTTY) {
+      console.error("Reading from stdin... (Ctrl+D to finish)");
+    }
+  });
+}
+
+main().catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/dist/config.js

@@ -0,0 +1,25 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const CONFIG_DIR = join(homedir(), ".config", "jotbird");
+const CREDENTIALS_FILE = join(CONFIG_DIR, "credentials");
+
+export function getApiKey() {
+  try {
+    return readFileSync(CREDENTIALS_FILE, "utf-8").trim();
+  } catch {
+    return null;
+  }
+}
+
+export function saveApiKey(key) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CREDENTIALS_FILE, key + "\n", { mode: 0o600 });
+}
+
+export function getCredentialsPath() {
+  return CREDENTIALS_FILE;
+}
+
+export const API_BASE = process.env.JOTBIRD_API_URL || "https://www.jotbird.com";

package/dist/files.js

@@ -0,0 +1,12 @@
+export const ALLOWED_EXTENSIONS = new Set([
+  ".md", ".markdown", ".mdx", ".txt", ".text",
+]);
+
+export function isAllowedFile(filename) {
+  const base = filename.includes("/") ? filename.slice(filename.lastIndexOf("/") + 1) : filename;
+  const dotIndex = base.lastIndexOf(".");
+  // No extension (e.g. "README") — allow it
+  if (dotIndex <= 0) return true;
+  const ext = base.slice(dotIndex).toLowerCase();
+  return ALLOWED_EXTENSIONS.has(ext);
+}

package/dist/login.js

@@ -0,0 +1,78 @@
+import { createServer } from "node:http";
+
+/**
+ * Start a temporary HTTP server on 127.0.0.1 that waits for the web app
+ * to redirect back with an API token via query parameter.
+ *
+ * Resolves with { port, tokenPromise, close }.
+ * - port: the randomly-assigned port the server is listening on
+ * - tokenPromise: resolves with the token string once /callback?token=... is hit
+ * - close: shuts down the server and clears the timeout
+ *
+ * The server automatically rejects tokenPromise after `timeoutMs` (default 5 min).
+ */
+export function startCallbackServer(timeoutMs = 300_000) {
+  return new Promise((resolve, reject) => {
+    let resolveToken, rejectToken;
+    const tokenPromise = new Promise((res, rej) => {
+      resolveToken = res;
+      rejectToken = rej;
+    });
+
+    const timeout = setTimeout(() => rejectToken(new Error("timeout")), timeoutMs);
+
+    const server = createServer((req, res) => {
+      const url = new URL(req.url, "http://127.0.0.1");
+
+      if (url.pathname === "/callback") {
+        const token = url.searchParams.get("token");
+
+        res.writeHead(200, { "Content-Type": "text/html", Connection: "close" });
+        res.end([
+          "<!DOCTYPE html><html><head><title>JotBird CLI</title></head>",
+          '<body style="font-family:system-ui,sans-serif;display:flex;justify-content:center;align-items:center;min-height:100vh;margin:0;background:#f8fafc;color:#0f172a">',
+          '<div style="text-align:center;max-width:400px;padding:2rem">',
+          '<h1 style="font-size:1.5rem;font-weight:700;margin:0 0 .5rem">Logged in</h1>',
+          '<p style="color:#64748b;margin:0">You can close this tab and return to your terminal.</p>',
+          "</div></body></html>",
+        ].join(""));
+
+        if (token) {
+          clearTimeout(timeout);
+          resolveToken(token);
+        }
+      } else {
+        res.writeHead(404);
+        res.end();
+      }
+    });
+
+    server.listen(0, "127.0.0.1", () => {
+      resolve({
+        port: server.address().port,
+        tokenPromise,
+        close: () => { clearTimeout(timeout); server.close(); },
+      });
+    });
+
+    server.on("error", reject);
+  });
+}
+
+/**
+ * Try to open a URL in the user's default browser.
+ * Returns true if the command succeeded, false otherwise.
+ */
+export async function openBrowser(url) {
+  try {
+    const { execFile } = await import("node:child_process");
+    const cmd = process.platform === "darwin" ? "open"
+      : process.platform === "win32" ? "start"
+      : "xdg-open";
+    return new Promise((resolve) => {
+      execFile(cmd, [url], (err) => resolve(!err));
+    });
+  } catch {
+    return false;
+  }
+}

package/dist/mapping.js

@@ -0,0 +1,74 @@
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const MAPPING_FILE = ".jotbird";
+
+function getMappingPath() {
+  return join(process.cwd(), MAPPING_FILE);
+}
+
+/**
+ * Read the .jotbird mapping file.
+ * Returns a Map of filename → slug.
+ */
+export function readMappings() {
+  const path = getMappingPath();
+  const map = new Map();
+  if (!existsSync(path)) return map;
+
+  const content = readFileSync(path, "utf-8");
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eqIndex = trimmed.indexOf("=");
+    if (eqIndex === -1) continue;
+    const file = trimmed.slice(0, eqIndex).trim();
+    const slug = trimmed.slice(eqIndex + 1).trim();
+    if (file && slug) map.set(file, slug);
+  }
+  return map;
+}
+
+/**
+ * Write the .jotbird mapping file.
+ */
+export function writeMappings(map) {
+  const path = getMappingPath();
+  const lines = [];
+  for (const [file, slug] of map) {
+    lines.push(`${file} = ${slug}`);
+  }
+  writeFileSync(path, lines.join("\n") + "\n");
+}
+
+/**
+ * Update a single mapping and write to disk.
+ */
+export function setMapping(filename, slug) {
+  const map = readMappings();
+  map.set(filename, slug);
+  writeMappings(map);
+}
+
+/**
+ * Remove a mapping by filename or slug and write to disk.
+ * Returns true if a mapping was removed.
+ */
+export function removeMapping(filenameOrSlug) {
+  const map = readMappings();
+  // Try removing by filename first
+  if (map.has(filenameOrSlug)) {
+    map.delete(filenameOrSlug);
+    writeMappings(map);
+    return true;
+  }
+  // Try removing by slug value
+  for (const [file, slug] of map) {
+    if (slug === filenameOrSlug) {
+      map.delete(file);
+      writeMappings(map);
+      return true;
+    }
+  }
+  return false;
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "jotbird",
+  "version": "0.1.0",
+  "description": "Publish Markdown from the command line with JotBird",
+  "type": "module",
+  "bin": {
+    "jotbird": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "node build.js",
+    "dev": "node src/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": ["markdown", "publish", "jotbird", "cli"],
+  "license": "MIT"
+}