fns-cli 0.4.0__py3-none-any.whl

fns.py

@@ -0,0 +1,811 @@
+#!/usr/bin/env python3
+"""Fast Note Sync (FNS) CLI - Interact with your Obsidian FNS service from terminal."""
+import sys, json, subprocess, os
+from pathlib import Path
+from urllib.parse import urlencode
+from datetime import datetime, timezone
+
+# Fix Windows console encoding for emoji support
+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONIOENCODING", "utf-8")
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+import click
+
+__version__ = "0.4.0"
+
+# Config directory: ~/.config/fns-cli/ (cross-platform, consistent with other CLI tools)
+CONFIG_DIR = Path.home() / ".config" / "fns-cli"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+TOKEN_FILE = CONFIG_DIR / "token"
+
+DEFAULT_BASE_URL = ""  # Configure via 'fns config url'
+DEFAULT_VAULT = ""  # Auto-detected on first login
+
+# Global state for output mode
+_ctx = {}
+
+def _echo(text, **kwargs):
+    """Print unless quiet mode is enabled."""
+    if not _ctx.get("quiet"):
+        click.echo(text, **kwargs)
+
+def format_timestamp(ts_ms):
+    """Convert millisecond Unix timestamp to human-readable local time."""
+    if not ts_ms:
+        return ""
+    try:
+        dt = datetime.fromtimestamp(int(ts_ms) / 1000, tz=timezone.utc).astimezone()
+        return dt.strftime("%Y-%m-%d %H:%M:%S")
+    except (ValueError, OSError, OverflowError):
+        return str(ts_ms)
+
+def load_config():
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    if CONFIG_FILE.exists():
+        return json.loads(CONFIG_FILE.read_text())
+    return {"base_url": DEFAULT_BASE_URL, "vault": DEFAULT_VAULT}
+
+def save_config(cfg):
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(json.dumps(cfg, indent=2))
+
+def require_vault():
+    """Check if vault is configured, print hint if not."""
+    cfg = load_config()
+    vault = cfg.get("vault", "")
+    if not vault:
+        if _ctx.get("json_output"):
+            click.echo(json.dumps({"error": "Vault not configured", "hint": "Run: fns vaults or fns config vault <name>"}))
+            sys.exit(1)
+        click.echo("⚠️ Vault not configured. Run one of these:")
+        click.echo("   fns vaults          # List available vaults")
+        click.echo("   fns config vault <name>  # Set your vault")
+        sys.exit(1)
+    return vault
+
+def get_token():
+    if TOKEN_FILE.exists():
+        return TOKEN_FILE.read_text().strip()
+    if _ctx.get("json_output"):
+        click.echo(json.dumps({"error": "Token not found", "hint": "Run: fns login"}))
+        sys.exit(1)
+    _echo("⚠️ Token not found. Run: fns login", err=True)
+    sys.exit(1)
+
+def _handle_response(data, success_msg=None, error_prefix="Failed"):
+    """Handle API response, print success or error based on code/status."""
+    code = data.get("code", 0)
+    status = data.get("status", False)
+
+    if _ctx.get("json_output"):
+        click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+        # Don't exit in JSON mode for errors, let caller handle
+        return data
+
+    # Success: code 1-6 OR status is True
+    if code in range(1, 7) or status is True:
+        if success_msg:
+            _echo(success_msg)
+        return data
+    else:
+        msg = data.get("message", json.dumps(data, indent=2, ensure_ascii=False))
+        _echo(f"❌ {error_prefix}: {msg}", err=True)
+        sys.exit(1)
+
+def curl_request(method, endpoint, params=None, json_data=None):
+    cfg = load_config()
+    base_url = cfg.get("base_url", "")
+    if not base_url:
+        if _ctx.get("json_output"):
+            click.echo(json.dumps({"error": "API URL not configured", "hint": "Run: fns config url <url>"}))
+            sys.exit(1)
+        _echo("⚠️ API URL not configured. Run: fns config url https://your-server/api", err=True)
+        sys.exit(1)
+
+    url = f"{base_url}{endpoint}"
+    if params:
+        url += f"?{urlencode(params)}"
+
+    cmd = ["curl", "-s", "-X", method, url,
+           "-H", f"Authorization: Bearer {get_token()}"]
+
+    if json_data is not None:
+        cmd.extend(["-H", "Content-Type: application/json",
+                    "-d", json.dumps(json_data)])
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=15, encoding="utf-8", errors="replace")
+        if result.returncode != 0:
+            if _ctx.get("json_output"):
+                click.echo(json.dumps({"error": "curl error", "detail": result.stderr.strip()}))
+                sys.exit(1)
+            _echo(f"❌ curl error: {result.stderr.strip()}", err=True)
+            sys.exit(1)
+        return json.loads(result.stdout)
+    except subprocess.TimeoutExpired:
+        if _ctx.get("json_output"):
+            click.echo(json.dumps({"error": "Request timed out"}))
+            sys.exit(1)
+        _echo("❌ Request timed out", err=True)
+        sys.exit(1)
+    except json.JSONDecodeError:
+        if _ctx.get("json_output"):
+            click.echo(json.dumps({"error": "Invalid JSON response", "detail": result.stdout[:200]}))
+            sys.exit(1)
+        _echo(f"❌ Invalid JSON response: {result.stdout[:200]}", err=True)
+        sys.exit(1)
+
+# ==================== Click CLI ====================
+
+@click.group()
+@click.version_option(__version__, prog_name="fns-cli")
+@click.option("-q", "--quiet", is_flag=True, help="Suppress non-essential output")
+@click.option("--json", "json_output", is_flag=True, help="Output in JSON format")
+@click.pass_context
+def cli(ctx, quiet, json_output):
+    """📝 Fast Note Sync CLI - Interact with your Obsidian FNS service."""
+    _ctx["quiet"] = quiet
+    _ctx["json_output"] = json_output
+
+@cli.command()
+@click.argument("credentials", required=False)
+@click.argument("password", required=False)
+@click.option("-u", "--url", "api_url", help="Set API URL before login")
+def login(credentials, password, api_url):
+    """Login and save token (password will be hidden if not provided)."""
+    cfg = load_config()
+
+    # Step 1: Ensure URL is configured
+    base_url = cfg.get("base_url", "")
+    if api_url:
+        url_val = api_url.rstrip("/")
+        if not url_val.endswith("/api"):
+            url_val += "/api"
+        cfg["base_url"] = url_val
+        save_config(cfg)
+        _echo(f"✅ API URL set to '{url_val}'")
+        base_url = url_val
+    elif not base_url:
+        base_url = click.prompt("Enter FNS server URL (e.g., https://your-server)")
+        base_url = base_url.rstrip("/")
+        if not base_url.endswith("/api"):
+            base_url += "/api"
+        cfg["base_url"] = base_url
+        save_config(cfg)
+        _echo(f"✅ API URL set to '{base_url}'")
+
+    # Step 2: Prompt for credentials if not provided
+    if not credentials:
+        credentials = click.prompt("Username or email")
+    if not password:
+        password = click.prompt("Password", hide_input=True)
+
+    # Step 3: Authenticate
+    url = f"{base_url}/user/login"
+    cmd = ["curl", "-s", "-X", "POST", url,
+           "-H", "Content-Type: application/json",
+           "-d", json.dumps({"Credentials": credentials, "Password": password})]
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=15, encoding="utf-8", errors="replace")
+        resp = json.loads(result.stdout)
+        if _ctx.get("json_output"):
+            click.echo(json.dumps(resp, indent=2, ensure_ascii=False))
+            return
+
+        if resp.get("status") or resp.get("code", 0) >= 1:
+            token = resp.get("data", {}).get("token")
+            if token:
+                TOKEN_FILE.write_text(token)
+                _echo(f"✅ Login successful. Token saved to {TOKEN_FILE}")
+
+                # Step 4: Handle vault selection
+                if not cfg.get("vault"):
+                    vault_data = curl_request("GET", "/vault")
+                    vaults_list = []
+                    if isinstance(vault_data.get("data"), list):
+                        vaults_list = vault_data["data"]
+                    elif isinstance(vault_data.get("data"), dict):
+                        vaults_list = vault_data["data"].get("list", [vault_data["data"]])
+
+                    if len(vaults_list) == 1:
+                        v = vaults_list[0]
+                        vault_name = v.get("vault", v.get("name", v.get("vault_name", str(v.get("id", "")))))
+                        cfg["vault"] = vault_name
+                        save_config(cfg)
+                        _echo(f"📦 Auto-set vault to '{vault_name}'")
+                    elif vaults_list:
+                        _echo("📦 Available vaults:")
+                        choices = []
+                        for i, v in enumerate(vaults_list, 1):
+                            name = v.get("vault", v.get("name", v.get("vault_name", str(v.get("id", "")))))
+                            choices.append(str(i))
+                            _echo(f"  {i}. {name}")
+                        selected = click.prompt("Select vault", type=click.Choice(choices), default=choices[0])
+                        idx = int(selected) - 1
+                        v = vaults_list[idx]
+                        vault_name = v.get("vault", v.get("name", v.get("vault_name", str(v.get("id", "")))))
+                        cfg["vault"] = vault_name
+                        save_config(cfg)
+                        _echo(f"📦 Vault set to '{vault_name}'")
+                _echo("🎉 Ready! Try: fns list")
+            else:
+                _echo("❌ No token in response.", err=True)
+        else:
+            _echo(f"❌ Login failed: {resp.get('message', 'Unknown error')}", err=True)
+    except Exception as e:
+        _echo(f"❌ Error: {e}", err=True)
+
+@cli.command()
+@click.argument("path")
+def read(path):
+    """Read a note."""
+    vault = require_vault()
+    data = curl_request("GET", "/note", params={"vault": vault, "path": path})
+    if _ctx.get("json_output"):
+        click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+
+    content = data.get("data", {}).get("content") if isinstance(data.get("data"), dict) else None
+    if content is not None:
+        _echo(f"📄 {path}\n{'-'*40}\n{content}")
+    else:
+        _echo(f"❌ Unexpected response: {json.dumps(data, indent=2, ensure_ascii=False)}", err=True)
+
+@cli.command()
+@click.argument("path")
+@click.argument("content_or_file")
+def write(path, content_or_file):
+    """Create/Update note (use @file.txt for local file)."""
+    vault = require_vault()
+    if content_or_file.startswith("@"):
+        file_path = content_or_file[1:]
+        if Path(file_path).exists():
+            content = Path(file_path).read_text(encoding="utf-8")
+        else:
+            _echo(f"❌ File not found: {file_path}", err=True)
+            return
+    elif Path(content_or_file).exists():
+        content = Path(content_or_file).read_text(encoding="utf-8")
+    else:
+        content = content_or_file
+
+    data = curl_request("POST", "/note", json_data={"vault": vault, "path": path, "content": content})
+    _handle_response(data, success_msg=f"✅ Note '{path}' updated. Syncing to all devices...")
+
+@cli.command()
+@click.argument("path")
+@click.argument("content")
+def append(path, content):
+    """Append text to a note (use @file.txt for local file)."""
+    vault = require_vault()
+    if content.startswith("@"):
+        file_path = content[1:]
+        if Path(file_path).exists():
+            content = Path(file_path).read_text(encoding="utf-8")
+        else:
+            _echo(f"❌ File not found: {file_path}", err=True)
+            return
+
+    params = {"vault": vault, "path": path}
+    read_resp = curl_request("GET", "/note", params=params)
+    existing = ""
+    if isinstance(read_resp.get("data"), dict):
+        existing = read_resp["data"].get("content", "")
+
+    if existing and not existing.endswith("\n\n"):
+        if existing.endswith("\n"):
+            content = "\n" + content
+        else:
+            content = "\n\n" + content
+
+    data = curl_request("POST", "/note/append", json_data={"vault": vault, "path": path, "content": content})
+    _handle_response(data, success_msg=f"✅ Appended to '{path}'.")
+
+@cli.command()
+@click.argument("path")
+def delete(path):
+    """Delete a note (move to recycle bin)."""
+    vault = require_vault()
+    data = curl_request("DELETE", "/note", params={"vault": vault, "path": path})
+    _handle_response(data, success_msg=f"✅ Note '{path}' deleted (moved to recycle bin).")
+
+@cli.command()
+@click.argument("path")
+@click.argument("content_or_file")
+def prepend(path, content_or_file):
+    """Prepend text to a note (after frontmatter, use @file.txt for local file)."""
+    vault = require_vault()
+    if content_or_file.startswith("@"):
+        file_path = content_or_file[1:]
+        if Path(file_path).exists():
+            content = Path(file_path).read_text(encoding="utf-8")
+        else:
+            _echo(f"❌ File not found: {file_path}", err=True)
+            return
+    else:
+        content = content_or_file
+
+    data = curl_request("POST", "/note/prepend", json_data={"vault": vault, "path": path, "content": content})
+    _handle_response(data, success_msg=f"✅ Prepended to '{path}'.")
+
+@cli.command()
+@click.argument("path")
+@click.argument("search")
+@click.argument("replace_text")
+def replace(path, search, replace_text):
+    """Find and replace in note."""
+    vault = require_vault()
+    data = curl_request("POST", "/note/replace", json_data={
+        "vault": vault, "path": path, "find": search, "replace": replace_text
+    })
+    if _ctx.get("json_output"):
+        click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+
+    if data.get("code", 0) >= 1 or data.get("status"):
+        replacements = data.get("data", {}).get("count", "?")
+        _echo(f"✅ Replaced {replacements} occurrence(s) in '{path}'.")
+    else:
+        _echo(f"❌ Failed to replace: {json.dumps(data, indent=2, ensure_ascii=False)}", err=True)
+
+@cli.command(name="move")
+@click.argument("old_path")
+@click.argument("new_path")
+def move_note(old_path, new_path):
+    """Move/rename a note."""
+    vault = require_vault()
+    data = curl_request("POST", "/note/move", json_data={
+        "vault": vault, "path": old_path, "destination": new_path
+    })
+    _handle_response(data, success_msg=f"✅ Moved '{old_path}' → '{new_path}'.")
+
+@cli.command()
+@click.argument("path")
+@click.option("--page", default=1, help="Page number")
+def history(path, page):
+    """Show note history."""
+    vault = require_vault()
+    data = curl_request("GET", "/note/histories", params={
+        "vault": vault, "path": path, "page": page, "pageSize": 20
+    })
+    if _ctx.get("json_output"):
+        click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+
+    histories = []
+    if isinstance(data.get("data"), dict):
+        histories = data["data"].get("list", [])
+    elif isinstance(data.get("data"), list):
+        histories = data["data"]
+
+    if histories:
+        _echo(f"📜 History for '{path}':\n")
+        for h in histories:
+            hid = h.get("id", h.get("historyId", ""))
+            mtime = h.get("mtime", h.get("updatedTimestamp", h.get("createdTimestamp", "")))
+            readable = format_timestamp(mtime) if mtime else ""
+            size = h.get("size", h.get("contentLength", ""))
+            _echo(f"  📄 [{hid}] {readable} ({size} bytes)")
+        _echo()
+    else:
+        _echo(f"📭 No history found for '{path}'.")
+
+@cli.command("list")
+@click.argument("keyword", required=False, default="")
+@click.option("--page", default=1, help="Page number")
+def list_notes(keyword, page):
+    """List notes (optional keyword search)."""
+    vault = require_vault()
+    data = curl_request("GET", "/notes", params={"vault": vault, "keyword": keyword, "page": page, "pageSize": 20})
+
+    if _ctx.get("json_output"):
+        click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+
+    notes = []
+    pager_info = {}
+    if isinstance(data.get("data"), dict):
+        notes = data["data"].get("list", [])
+        pager_info = data["data"].get("pager", {})
+    elif isinstance(data, dict):
+        notes = data.get("list", data.get("notes", []))
+
+    if notes:
+        total = pager_info.get("totalRows", len(notes)) if pager_info else len(notes)
+        _echo(f"📚 Notes in '{vault}' (Page {page}):\n")
+        for n in notes:
+            path = n.get("path", n.get("name", n.get("title", "unknown")))
+            mtime = n.get("mtime", n.get("modified", ""))
+            if mtime:
+                _echo(f"  📄 {path} ({format_timestamp(mtime)})")
+            else:
+                _echo(f"  📄 {path}")
+        _echo(f"\nTotal: {total}")
+    else:
+        _echo("📭 No notes found.")
+
+@cli.command()
+def vaults():
+    """List available vaults."""
+    data = curl_request("GET", "/vault")
+    if _ctx.get("json_output"):
+        click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+
+    vault_list = []
+    if isinstance(data.get("data"), list):
+        vault_list = data["data"]
+    elif isinstance(data.get("data"), dict):
+        vault_list = data["data"].get("list", [data["data"]])
+
+    if vault_list:
+        _echo("📦 Available vaults:")
+        for v in vault_list:
+            name = v.get("vault", v.get("name", v.get("vault_name", v.get("id", "unknown"))))
+            _echo(f"  🗄️  {name}")
+    else:
+        _echo(f"📭 No vaults found.")
+
+@cli.command()
+def info():
+    """Show current user info."""
+    data = curl_request("GET", "/user/info")
+    if _ctx.get("json_output"):
+        click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+
+    user = data.get("data", {})
+    if user:
+        _echo("👤 Current user:")
+        for key in ("username", "email", "displayName", "id", "role"):
+            if key in user and user[key]:
+                _echo(f"  {key}: {user[key]}")
+    else:
+        _echo(f"❌ Failed to fetch user info.", err=True)
+
+@cli.group()
+def config():
+    """Manage configuration."""
+    pass
+
+@config.command("show")
+def config_show():
+    """Show current configuration."""
+    cfg = load_config()
+    base_url = cfg.get("base_url", "(not configured)")
+    vault = cfg.get("vault", "(not configured)")
+
+    _echo("📋 Current configuration:")
+    _echo(f"  API URL : {base_url}")
+    _echo(f"  Vault   : {vault}")
+
+    # Fetch user info if token exists
+    if TOKEN_FILE.exists():
+        try:
+            data = curl_request("GET", "/user/info")
+            user = data.get("data", {})
+            if user:
+                username = user.get("username", user.get("email", user.get("displayName", "")))
+                if username:
+                    _echo(f"  User    : {username}")
+                else:
+                    _echo("  User    : (logged in, no username)")
+            else:
+                _echo("  User    : (token invalid)")
+        except SystemExit:
+            _echo("  User    : (could not fetch)")
+    else:
+        _echo("  User    : (not logged in)")
+
+@config.command()
+@click.argument("value")
+def vault(value):
+    """Set vault name."""
+    cfg = load_config()
+    cfg["vault"] = value
+    save_config(cfg)
+    _echo(f"✅ Vault set to '{value}'")
+
+@config.command()
+@click.argument("value")
+def url(value):
+    """Set API URL."""
+    url_val = value.rstrip("/")
+    if not url_val.endswith("/api"):
+        url_val += "/api"
+    cfg = load_config()
+    cfg["base_url"] = url_val
+    save_config(cfg)
+    _echo(f"✅ API URL set to '{url_val}'")
+
+@cli.command()
+@click.argument("path", required=False, default="")
+def tree(path):
+    """Show vault folder tree structure."""
+    vault = require_vault()
+    params = {"vault": vault}
+    if path:
+        params["path"] = path
+    data = curl_request("GET", "/folder/tree", params=params)
+    if _ctx.get("json_output"):
+        click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+
+    tree_data = data.get("data", {})
+    if tree_data:
+        _echo(f"📂 Vault tree for '{vault}'" + (f" > {path}" if path else "") + ":\n")
+        _print_tree(tree_data, indent=0)
+    else:
+        _echo("📭 No tree data found.")
+
+def _print_tree(node, indent=0):
+    """Recursively print tree structure."""
+    prefix = "  " * indent + ("├─ " if indent > 0 else "")
+    name = node.get("name", node.get("path", "unknown"))
+    node_type = node.get("type", node.get("isFolder", "file"))
+    icon = "📁" if node_type in ("folder", True) or node.get("isFolder") else "📄"
+    _echo(f"{prefix}{icon} {name}")
+    children = node.get("children", node.get("sub", []))
+    if children:
+        for child in children:
+            _print_tree(child, indent + 1)
+
+@cli.command()
+@click.argument("path")
+def backlinks(path):
+    """Show notes that link to this note (backlinks)."""
+    vault = require_vault()
+    data = curl_request("GET", "/note/backlinks", params={"vault": vault, "path": path})
+    if _ctx.get("json_output"):
+        click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+
+    links = data.get("data", {}).get("list", data.get("data", []))
+    if isinstance(links, dict):
+        links = links.get("list", [])
+    if links:
+        _echo(f"🔗 Backlinks for '{path}':\n")
+        for link in links:
+            link_path = link.get("path", link.get("name", "unknown"))
+            _echo(f"  📄 {link_path}")
+        _echo(f"\nTotal: {len(links)}")
+    else:
+        _echo(f"📭 No backlinks found for '{path}'.")
+
+@cli.command()
+@click.argument("path")
+def outlinks(path):
+    """Show notes that this note links to (outlinks)."""
+    vault = require_vault()
+    data = curl_request("GET", "/note/outlinks", params={"vault": vault, "path": path})
+    if _ctx.get("json_output"):
+        click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+
+    links = data.get("data", {}).get("list", data.get("data", []))
+    if isinstance(links, dict):
+        links = links.get("list", [])
+    if links:
+        _echo(f"🔗 Outlinks from '{path}':\n")
+        for link in links:
+            link_path = link.get("path", link.get("name", "unknown"))
+            _echo(f"  📄 {link_path}")
+        _echo(f"\nTotal: {len(links)}")
+    else:
+        _echo(f"📭 No outlinks found for '{path}'.")
+
+@cli.command()
+@click.argument("path")
+def restore(path):
+    """Restore a note from the recycle bin."""
+    vault = require_vault()
+    data = curl_request("POST", "/note/restore", json_data={"vault": vault, "path": path})
+    _handle_response(data, success_msg=f"✅ Restored '{path}' from recycle bin.")
+
+@cli.command()
+@click.argument("path")
+@click.option("--set", "set_pairs", multiple=True, help="Set frontmatter key=value (can be repeated)")
+@click.option("--remove", "remove_keys", multiple=True, help="Remove frontmatter keys (can be repeated)")
+def frontmatter(path, set_pairs, remove_keys):
+    """View or edit note frontmatter."""
+    vault = require_vault()
+
+    # If no changes, just display current frontmatter
+    if not set_pairs and not remove_keys:
+        data = curl_request("GET", "/note", params={"vault": vault, "path": path})
+        if _ctx.get("json_output"):
+            click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+            return
+        content = data.get("data", {}).get("content", "")
+        if content:
+            # Extract frontmatter (between --- markers)
+            if content.startswith("---"):
+                parts = content.split("---", 2)
+                if len(parts) >= 3:
+                    fm = parts[1].strip()
+                    _echo(f"📋 Frontmatter for '{path}':\n{fm}")
+                    return
+            _echo(f"📋 No frontmatter found for '{path}'.")
+        return
+
+    # Apply changes
+    fm_data = {}
+    for pair in set_pairs:
+        if "=" in pair:
+            key, val = pair.split("=", 1)
+            fm_data[key.strip()] = val.strip()
+
+    data = curl_request("PATCH", "/note/frontmatter", json_data={
+        "vault": vault, "path": path, "frontmatter": fm_data, "removeKeys": list(remove_keys)
+    })
+    _handle_response(data, success_msg=f"✅ Frontmatter updated for '{path}'.")
+
+@cli.command()
+@click.argument("path")
+@click.option("--expire", help="Expiration time (ISO 8601 or duration like 24h)")
+@click.option("--password", help="Access password for the shared link")
+def share(path, expire, password):
+    """Create a shareable link for a note."""
+    vault = require_vault()
+    payload = {"vault": vault, "path": path}
+    if expire:
+        payload["expire"] = expire
+    if password:
+        payload["password"] = password
+
+    data = curl_request("POST", "/api/share", json_data=payload)
+    if _ctx.get("json_output"):
+        click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+
+    share_data = data.get("data", {})
+    if share_data:
+        token = share_data.get("token", share_data.get("shareToken", ""))
+        url = share_data.get("url", share_data.get("shareUrl", ""))
+        _echo(f"🔗 Share link created for '{path}':")
+        if url:
+            _echo(f"  URL: {url}")
+        if token:
+            _echo(f"  Token: {token}")
+        if expire:
+            _echo(f"  Expires: {expire}")
+    else:
+        _echo(f"❌ Failed to create share link: {json.dumps(data, indent=2, ensure_ascii=False)}", err=True)
+
+@cli.command()
+@click.argument("path")
+def unshare(path):
+    """Remove sharing for a note."""
+    vault = require_vault()
+    data = curl_request("DELETE", "/api/share", json_data={"vault": vault, "path": path})
+    _handle_response(data, success_msg=f"✅ Sharing removed for '{path}'.")
+
+@cli.command()
+@click.argument("vault_id", required=False, default="")
+def vault_info(vault_id):
+    """Show vault details."""
+    if not vault_id:
+        # If no ID provided, show current vault info
+        vault = require_vault()
+        # Try to get vault info by listing vaults and finding current one
+        data = curl_request("GET", "/vault")
+        vaults_list = []
+        if isinstance(data.get("data"), list):
+            vaults_list = data["data"]
+        elif isinstance(data.get("data"), dict):
+            vaults_list = data["data"].get("list", [data["data"]])
+
+        for v in vaults_list:
+            name = v.get("vault", v.get("name", v.get("vault_name", str(v.get("id", "")))))
+            if name == vault:
+                vault_id = str(v.get("id", ""))
+                break
+
+    if not vault_id:
+        _echo("❌ Vault ID not found.", err=True)
+        return
+
+    data = curl_request("GET", "/vault/get", params={"id": vault_id})
+    if _ctx.get("json_output"):
+        click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+
+    info = data.get("data", {})
+    if info:
+        _echo(f"📦 Vault info (ID: {vault_id}):")
+        for key in ("vault", "name", "noteCount", "noteSize", "fileCount", "fileSize", "createdAt", "updatedAt"):
+            if key in info and info[key]:
+                _echo(f"  {key}: {info[key]}")
+    else:
+        _echo(f"❌ Vault not found: {vault_id}", err=True)
+
+@cli.command("recycle-bin")
+@click.argument("path", required=False, default="")
+def recycle_bin(path):
+    """Show notes in the recycle bin."""
+    vault = require_vault()
+    params = {"vault": vault, "isRecycle": "true", "page": 1, "pageSize": 50}
+    if path:
+        params["keyword"] = path
+    data = curl_request("GET", "/notes", params=params)
+
+    if _ctx.get("json_output"):
+        click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+
+    notes = []
+    if isinstance(data.get("data"), dict):
+        notes = data["data"].get("list", [])
+    elif isinstance(data, dict):
+        notes = data.get("list", data.get("notes", []))
+
+    if notes:
+        _echo("🗑️  Recycle bin:\n")
+        for n in notes:
+            note_path = n.get("path", n.get("name", n.get("title", "unknown")))
+            mtime = n.get("mtime", n.get("modified", ""))
+            readable = format_timestamp(mtime) if mtime else ""
+            _echo(f"  📄 {note_path} ({readable})")
+        _echo(f"\nTotal: {len(notes)}")
+    else:
+        _echo("📭 Recycle bin is empty.")
+
+@cli.command()
+def version():
+    """Show server version."""
+    data = curl_request("GET", "/version")
+    if _ctx.get("json_output"):
+        click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+
+    info = data.get("data", data)
+    if info:
+        _echo("📋 Server version:")
+        for key in ("version", "gitTag", "buildTime", "goVersion"):
+            if key in info and info[key]:
+                _echo(f"  {key}: {info[key]}")
+    else:
+        _echo(f"❌ Failed to get version info.", err=True)
+
+@cli.command()
+def health():
+    """Check server health status."""
+    data = curl_request("GET", "/health")
+    if _ctx.get("json_output"):
+        click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+
+    status = data.get("status", data.get("code", 0))
+    if status is True or (isinstance(status, int) and status >= 1):
+        _echo("✅ Server is healthy.")
+    else:
+        _echo(f"⚠️ Server health check: {json.dumps(data, indent=2, ensure_ascii=False)}")
+
+@cli.command("vault-create")
+@click.argument("name")
+def vault_create(name):
+    """Create a new vault (requires confirmation)."""
+    vault = require_vault()  # Ensure user is authenticated
+    click.confirm(f"⚠️ Create new vault '{name}'? This action cannot be undone", abort=True)
+
+    data = curl_request("POST", "/vault", json_data={"vault": name})
+    _handle_response(data, success_msg=f"✅ Vault '{name}' created.")
+
+@cli.command("vault-delete")
+@click.argument("vault_id")
+def vault_delete(vault_id):
+    """Delete a vault by ID (requires double confirmation)."""
+    # First confirmation
+    click.confirm(f"⚠️ WARNING: This will permanently delete vault ID '{vault_id}' and ALL its data!", abort=True)
+    # Second confirmation
+    click.confirm("🚨 Are you absolutely sure? This action CANNOT be undone!", abort=True)
+
+    data = curl_request("DELETE", "/vault", params={"id": vault_id})
+    _handle_response(data, success_msg=f"✅ Vault '{vault_id}' deleted permanently.")
+
+if __name__ == "__main__":
+    cli()

fns_cli-0.4.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 crazykuma
+
+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.

fns_cli-0.4.0.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.1
+Name: fns-cli
+Version: 0.4.0
+Summary: CLI tool for Fast Note Sync (Obsidian)
+Home-page: https://github.com/crazykuma/fns-cli
+Author: crazykuma
+License: MIT
+Project-URL: Homepage, https://github.com/crazykuma/fns-cli
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click >=8.1
+
+**Languages**: 🇺🇸 English | [🇨🇳 中文](README.zh.md)
+
+---
+
+# FNS CLI (Fast Note Sync CLI)
+
+> **From Local to Cloud**: Transform Obsidian notes from locally-managed files into **cloud-managed, AI-accessible knowledge**. Edit once, sync everywhere.
+
+FNS CLI is a powerful command-line tool for interacting with the **[Fast Note Sync (FNS)](https://github.com/haierkeys/fast-note-sync-service)** service. Manage, read, write, and sync your Obsidian notes directly from the terminal — optimized for both **human workflows** and **AI Agent integration**.
+
+## 🎯 Design Philosophy
+
+This tool bridges the gap between **local Obsidian editing** and **cloud-based AI knowledge management**:
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│  Obsidian App   │────▶│  FNS Service     │◀────│  FNS CLI (this) │
+│  (Desktop/Mobile│     │  (Cloud Server)  │     │  (Terminal/AI)  │
+│   Editor)       │◀────│                  │────▶│  (read/write)   │
+└─────────────────┘     └──────────────────┘     └─────────────────┘
+                                                         │
+                                              ┌──────────▼──────────┐
+                                              │  AI Agents           │
+                                              │  Claude Code,        │
+                                              │  OpenCode, Cursor... │
+                                              └─────────────────────┘
+```
+
+**One edit/update → all devices synced.** Whether you write in Obsidian on your desktop or manage notes via CLI/AI on a server, everything stays in sync through the FNS cloud service.
+
+## ✨ Features
+
+### Core
+- **Full Note CRUD** — Create, read, update, append, prepend, move, delete
+- **Smart Append** — Automatically handles newlines to prevent content merging
+- **Local File Upload** — Use `@file.txt` prefix to upload any local file
+- **Note History** — View and restore previous versions
+- **Recycle Bin** — Recover deleted notes
+- **Find & Replace** — Search and replace content (supports regex)
+- **Cross-Platform** — macOS / Linux / Windows (Python 3.6+)
+
+### Knowledge Graph
+- **Backlinks** — See which notes link to the current note
+- **Outlinks** — See which notes the current note links to
+- **Folder Tree** — Browse your vault's directory structure
+
+### Sharing & Metadata
+- **Share Links** — Create shareable URLs with optional password and expiry
+- **Frontmatter Editing** — View and modify note metadata (tags, title, etc.)
+
+### AI Agent Friendly
+- **`--json` Mode** — Machine-readable output for AI parsing
+- **`--quiet` Mode** — Silent operation for scripting
+- **Zero interactive prompts** when arguments are provided
+
+### Administration
+- **Vault Management** — List, view details, create, delete vaults
+- **Server Status** — Check version and health
+- **Auto-Setup** — Interactive guide on first login (URL → credentials → vault selection)
+
+## 📦 Installation
+
+```bash
+git clone https://github.com/crazykuma/fns-cli.git
+cd fns-cli
+pip install -e .
+```
+
+This installs the `fns` command globally on your system.
+
+**Dependencies**: `click>=8.1` (installed automatically) + `curl` (pre-installed on most systems)
+
+## ⚙️ Quick Setup
+
+### First-Time (Interactive Guide)
+
+```bash
+fns login
+# Enter FNS server URL: https://your-server
+# Username or email: you@example.com
+# Password: **** (hidden)
+# 📦 Available vaults:
+#   1. defaultVault
+# Select vault [1]: 1
+# 🎉 Ready! Try: fns list
+```
+
+### Script-Friendly (Non-Interactive)
+
+```bash
+fns login -u https://your-server username password
+```
+
+### Manual Configuration
+
+```bash
+fns config url "https://your-server/api"
+```
+
+## 🚀 Command Reference
+
+### Authentication & Setup
+```bash
+fns login [user] [pass] [-u URL]  # Login (interactive if args omitted)
+fns config show                    # Show current configuration
+fns config url <value>             # Set API URL
+fns config vault <value>           # Set vault name
+```
+
+### Note CRUD
+```bash
+fns read <path>                    # Read a note
+fns write <path> <text|@file>      # Create/overwrite (use @ to upload local file)
+fns append <path> <text|@file>     # Append content (smart newline handling)
+fns prepend <path> <text|@file>    # Prepend content (after frontmatter)
+fns delete <path>                  # Delete note (moves to recycle bin)
+fns move <old> <new>               # Move/rename a note
+fns replace <path> <find> <replace> # Find and replace (supports regex)
+fns history <path>                 # View revision history
+fns restore <path>                 # Restore note from recycle bin
+```
+
+### Knowledge & Links
+```bash
+fns list [keyword]                 # List/search notes
+fns tree [path]                    # View folder tree structure
+fns backlinks <path>               # Notes linking to this one
+fns outlinks <path>                # Notes this one links to
+```
+
+### Sharing & Metadata
+```bash
+fns share <path> [--expire 24h] [--password secret]  # Create share link
+fns unshare <path>                 # Remove sharing
+fns frontmatter <path>             # View frontmatter
+fns frontmatter <path> --set key=value --remove key  # Edit frontmatter
+```
+
+### Vault & Server
+```bash
+fns vaults                         # List available vaults
+fns vault-info [id]                # Show vault details
+fns vault-create <name>            # Create vault (with confirmation)
+fns vault-delete <id>              # Delete vault (double confirmation)
+fns recycle-bin [keyword]          # View recycle bin
+fns version                        # Show server version
+fns health                         # Check server health
+fns info                           # Show current user info
+```
+
+### Global Flags
+```bash
+fns --json <command>               # Output as JSON (for AI/script parsing)
+fns --quiet <command>              # Suppress non-essential output
+fns --version / -v                 # Show version
+fns --help                         # Show help
+```
+
+## 🤖 AI Agent Integration
+
+This tool is designed to give AI agents **long-term memory and knowledge access**:
+
+- **Read Context**: `fns read` specific notes before coding tasks
+- **Auto-Documentation**: `fns append` changelogs to daily notes
+- **Knowledge Retrieval**: `fns list` / `fns tree` to discover relevant files
+- **Knowledge Graph**: `fns backlinks` / `fns outlinks` to find related notes
+
+**Example with AI Agent:**
+```bash
+# Ask AI to read context, work, then document
+fns read "projects/architecture.md" --json
+# ... AI works ...
+fns append "daily/2024-05-20.md" "- Completed architecture review"
+```
+
+## 📁 File Structure
+
+```
+fns-cli/
+├── fns.py              # Main CLI logic
+├── setup.py            # Installation script
+├── requirements.txt    # Dependencies
+├── tests/
+│   └── test_fns.py     # Unit tests
+├── README.md           # This file
+├── README.zh.md        # Chinese version
+├── skill.md            # Usage examples
+├── CHANGELOG.md        # Version history
+└── LICENSE             # MIT License
+```
+
+## 📖 Usage Examples
+
+For detailed examples, see the portable Skill at [`fns-skill/SKILL.md`](fns-skill/SKILL.md). You can copy the entire `fns-skill/` directory into your own AI agent's Skills folder (Qwen Code, Claude Code, etc.).
+
+## 🧪 Running Tests
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+## 🔗 Related Projects
+
+- **[fast-note-sync-service](https://github.com/haierkeys/fast-note-sync-service)** — The FNS backend server
+- **[obsidian-fast-note-sync](https://github.com/haierkeys/obsidian-fast-note-sync)** — Obsidian plugin
+
+## 📜 License
+
+MIT License — see [LICENSE](LICENSE).

fns_cli-0.4.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+fns.py,sha256=cuTZUE_S_h2hgHiJ27296AWcN4DBQ6GYwP1tBGTt22E,31072
+fns_cli-0.4.0.dist-info/LICENSE,sha256=jLzkeEmVeifYxrjYdb7wC3uNxoni6pto78dsrrYBcJE,1087
+fns_cli-0.4.0.dist-info/METADATA,sha256=EwVt58OS9-Rr4_kDHxMxrCZRgVwzVF3O48z1C2N2cdQ,8842
+fns_cli-0.4.0.dist-info/WHEEL,sha256=R0nc6qTxuoLk7ShA2_Y-UWkN8ZdfDBG2B6Eqpz2WXbs,91
+fns_cli-0.4.0.dist-info/entry_points.txt,sha256=z6L8PYKEGYrFOOCkBQ89ulMseM6x-j1trskvKQnELyg,32
+fns_cli-0.4.0.dist-info/top_level.txt,sha256=erNDyA50FAObwrbMr8av13iR3x5ZzhNZQXYauns0BOg,4
+fns_cli-0.4.0.dist-info/RECORD,,

fns_cli-0.4.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (72.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fns_cli-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fns = fns:cli

fns_cli-0.4.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fns