CLANGD(1)

💅 NAME 💅

clangd — the manual page for clangd 19, bestie 💖

---

✨ DESCRIPTION ✨

OVERVIEW: clangd is a language server that hands out IDE-like features to editors. It's giving brainpower-for-your-editor energy 🧠✨

🫶 It should be used via an editor plugin rather than invoked directly 🫶

Like, do NOT just run this raw, ok? It lives in your editor through a plugin. For more info, go look at:

• https://clangd.llvm.org/
• https://microsoft.github.io/language-server-protocol/

clangd accepts flags on the commandline, and also in the CLANGD_FLAGS environment variable — yes, both, it's flexible like that 🦋

🌸 USAGE 🌸

clangd [options]

🌈 OPTIONS 🌈

💖 Generic Options 💖

• --help — shows u all the available options 🥰 (there's --help-hidden for even more)
• --help-list — shows u the list of available options (and --help-list-hidden for more)
• --version — tells u what version of this program ur running, iconic

🎀 clangd compilation flags options 🎀

• --compile-commands-dir=<string> — points at a path to look for compile_commands.json. If that path is invalid, clangd goes looking in the current directory and the parent paths of each source file instead 🕵️‍♀️
• --query-driver=<string> — a comma separated list of globs white-listing gcc-compatible drivers that are safe to execute. Any driver matching one of these globs gets used to extract system includes. e.g. /usr/bin/**/clang-*,/path/to/repo/**/g++-* 🔥

👑 clangd feature options 👑

• --all-scopes-completion — if set to true, code completion will include index symbols that are not defined in the scopes (e.g. namespaces) visible from the code completion point. Such completions can insert scope qualifiers 💫
• --background-index — indexes project code in the background and persists the index on disk. No cap.
• --background-index-priority=<value> — thread priority for building the background index. Heads up, the effect of this flag is OS-specific 😭
  • background — minimum priority, runs on idle CPUs. May leave 'performance' cores unused.
  • low — reduced priority compared to interactive work.
  • normal — same priority as other clangd work.
• --clang-tidy — enables clang-tidy diagnostics 🧼
• --completion-style=<value> — the granularity of code completion suggestions:
  • detailed — one completion item for each semantically distinct completion, with full type information
  • bundled — similar completion items (e.g. function overloads) are combined. Type information shown where possible
• --experimental-modules-support — experimental support for standard c++ modules 🧪 (it literally says experimental, so, yk)
• --fallback-style=<string> — the clang-format style to apply by default when no .clang-format file is found
• --function-arg-placeholders — when disabled, completions contain only parentheses for function calls. When enabled, completions also contain placeholders for method parameters 🫶
• --header-insertion=<value> — adds #include directives when accepting code completions:
  • iwyu — include what you use. Insert the owning header for top-level symbols, unless the header is already directly included or the symbol is forward-declared
  • never — never insert #include directives as part of code completion
• --header-insertion-decorators — prepends a circular dot or a space before the completion label, depending on whether an include line will be inserted or not 💅
• --import-insertions — if header insertion is enabled, adds #import directives when accepting code completions or fixing includes in Objective-C code
• --limit-references=<int> — limits the number of references returned by clangd. 0 means no limit (default=1000)
• --limit-results=<int> — limits the number of results returned by clangd. 0 means no limit (default=100)
• --project-root=<string> — path to the project root. Requires remote-index-address to be set ⚠️
• --remote-index-address=<string> — the address of the remote index server 🌐
• --rename-file-limit=<int> — limits the number of files to be affected by symbol renaming. 0 means no limit (default=50)

🦋 clangd miscellaneous options 🦋

• --check[=<string>] — parses one file in isolation instead of acting as a language server. Super useful to investigate/reproduce crashes or configuration problems. With --check=<filename>, it attempts to parse that particular file 🔍
• --enable-config — reads user and project configuration from YAML files. Project config comes from a .clangd file in the project directory. User config comes from clangd/config.yaml in these directories:
  • Windows: %USERPROFILE%\AppData\Local
  • Mac OS: ~/Library/Preferences/
  • Others: $XDG_CONFIG_HOME, usually ~/.config

Configuration is documented at https://clangd.llvm.org/config.html 📖

• -j <uint> — number of async workers used by clangd. The background index also uses this many workers 💪
• --malloc-trim — releases memory periodically via malloc_trim(3).
• --pch-storage=<value> — storing PCHs in memory increases memory usages, but may improve performance 🫠
  • disk — store PCHs on disk
  • memory — store PCHs in memory

⭐ clangd protocol and logging options ⭐

• --log=<value> — verbosity of log messages written to stderr:
  • error — error messages only
  • info — high level execution tracing
  • verbose — low level details
• --offset-encoding=<value> — forces the offsetEncoding used for character positions. This bypasses negotiation via client capabilities 😤
  • utf-8 — offsets are in UTF-8 bytes
  • utf-16 — offsets are in UTF-16 code units
  • utf-32 — offsets are in unicode codepoints
• --path-mappings=<string> — translates between client paths (as seen by a remote editor) and server paths (where clangd sees files on disk). Comma separated list of '<client_path>=<server_path>' pairs, and the first entry matching a given path is the one used. e.g. /home/project/incl=/opt/include,/home/project=/workarea/project 🗺️
• --pretty — pretty-prints JSON output 🌸

---

okay that's the whole thing bestie, u got this 💖 This was the clangd(1) manual page for clangd 19, dated June 2025 — mwah, slay, periodt 👑💅✨