id          = "karakeep"
name        = "Karakeep CLI"
homepage    = "https://karakeep.app/"
description = "CLI tool for the self-hostable bookmark-everything app."
executables      = ["karakeep"]

[dotfiles]

# https://docs.karakeep.app/integrations/command-line/ — the CLI stores its
# server address and API key in config.json under XDG_CONFIG_HOME (falling
# back to ~/.config). The key makes this whole file credential material.
paths  = []
secret = ["[configHome]/karakeep/config.json"]

[commands]
format = 1
label = "Karakeep CLI"
description = "Add, list and search bookmarks. The server address and API key come from the config file or environment (KARAKEEP_SERVER_ADDR, KARAKEEP_API_KEY), not from this form; update, delete, lists and tags are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = false, short_attached = false, short_bundles = false }

[[commands.subcommand]]
path = ["bookmarks", "add"]
label = "Add bookmarks"
description = "Create bookmarks from links, notes or files."

[[commands.subcommand.source]]
id = "src"
kind = "help"
url = "https://github.com/karakeep-app/karakeep/blob/main/apps/cli/src/commands/bookmarks.ts"
revision = "main 2026-10-27"
evidence = """
.command("add")
"--link <link>",
"the link to add. Specify multiple times to add multiple links",
"--note <note>",
"--asset <file>",
"the file path of an asset (image or pdf) to add. Specify multiple times to add multiple assets",
"--list-id <id>",
"--tag-name <tag>",
"--title <title>",
"""

[[commands.subcommand.field]]
id = "link"
label = "Link"
type = "url"
option = ["--link"]
multiple = true
sources = ["src"]

[[commands.subcommand.field]]
id = "note"
label = "Note text"
type = "string"
option = ["--note"]
multiple = true
sources = ["src"]

[[commands.subcommand.field]]
id = "asset"
label = "Asset file (image or PDF)"
type = "path"
option = ["--asset"]
multiple = true
path = { kind = "file", role = "input", must_exist = true }
sources = ["src"]

[[commands.subcommand.field]]
id = "list_id"
label = "List ID"
type = "string"
option = ["--list-id"]
sources = ["src"]

[[commands.subcommand.field]]
id = "tag_name"
label = "Tag"
type = "string"
option = ["--tag-name"]
multiple = true
sources = ["src"]

[[commands.subcommand.field]]
id = "title"
label = "Title"
type = "string"
option = ["--title"]
sources = ["src"]

[[commands.subcommand.task]]
id = "add-link"
label = "Add a link"
fields = ["link", "title", "tag_name", "list_id"]
required = ["link"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["link", "note", "asset", "title"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["list_id", "tag_name"]

[[commands.subcommand]]
path = ["bookmarks", "search"]
label = "Search bookmarks"
description = "Search with matchers such as tag:name or is:fav."

[[commands.subcommand.source]]
id = "src"
kind = "help"
url = "https://github.com/karakeep-app/karakeep/blob/main/apps/cli/src/commands/bookmarks.ts"
revision = "main 2026-10-27"
evidence = """
.command("search")
"<query>",
"the search query (supports matchers like tag:name, is:fav, etc.)",
"--limit <limit>",
"--sort-order <order>",
"sort order for results",
if (val !== "relevance" && val !== "asc" && val !== "desc") {
"--search-mode <mode>",
if (val !== "fts" && val !== "semantic" && val !== "hybrid") {
"--include-content",
.option("--all", "fetch all results (paginate through all pages)", false)
"""

[[commands.subcommand.field]]
id = "query"
label = "Query"
type = "string"
position = 0
sources = ["src"]

[[commands.subcommand.field]]
id = "limit"
label = "Results per page"
type = "integer"
option = ["--limit"]
sources = ["src"]

[[commands.subcommand.field]]
id = "sort_order"
label = "Sort order"
type = "enum"
option = ["--sort-order"]
choices = [{ value = "relevance", label = "Relevance" }, { value = "asc", label = "Oldest first" }, { value = "desc", label = "Newest first" }]
sources = ["src"]

[[commands.subcommand.field]]
id = "search_mode"
label = "Search mode"
type = "enum"
option = ["--search-mode"]
choices = [{ value = "fts", label = "Full text" }, { value = "semantic", label = "Semantic" }, { value = "hybrid", label = "Hybrid" }]
sources = ["src"]

[[commands.subcommand.field]]
id = "include_content"
label = "Include full content"
type = "boolean"
option = ["--include-content"]
sources = ["src"]

[[commands.subcommand.field]]
id = "all"
label = "Fetch all pages"
type = "boolean"
option = ["--all"]
sources = ["src"]

[[commands.subcommand.task]]
id = "search"
label = "Search"
fields = ["query", "limit", "sort_order", "search_mode"]
required = ["query"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["query", "limit", "sort_order", "search_mode"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["include_content", "all"]

[[commands.subcommand]]
path = ["bookmarks", "list"]
label = "List bookmarks"
description = "List bookmarks, optionally for one list or tag."

[[commands.subcommand.source]]
id = "src"
kind = "help"
url = "https://github.com/karakeep-app/karakeep/blob/main/apps/cli/src/commands/bookmarks.ts"
revision = "main 2026-10-27"
evidence = """
.command("list")
"--include-archived",
"--list-id <id>", "if set, only items from that list will be fetched"
"--tag-id <id>", "if set, only items with that tag will be fetched"
"--include-content",
"--limit <limit>",
.option("--all", "fetch all bookmarks (paginate through all pages)", false)
"""

[[commands.subcommand.field]]
id = "include_archived"
label = "Include archived"
type = "boolean"
option = ["--include-archived"]
sources = ["src"]

[[commands.subcommand.field]]
id = "list_id"
label = "Only this list ID"
type = "string"
option = ["--list-id"]
sources = ["src"]

[[commands.subcommand.field]]
id = "tag_id"
label = "Only this tag ID"
type = "string"
option = ["--tag-id"]
sources = ["src"]

[[commands.subcommand.field]]
id = "limit"
label = "Bookmarks per page"
type = "integer"
option = ["--limit"]
sources = ["src"]

[[commands.subcommand.field]]
id = "all"
label = "Fetch all pages"
type = "boolean"
option = ["--all"]
sources = ["src"]

[[commands.subcommand.task]]
id = "list"
label = "List bookmarks"
fields = ["include_archived", "list_id", "tag_id", "limit", "all"]
required = []

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["include_archived", "list_id", "tag_id", "limit", "all"]