CLI
The ctxd CLI manages the local tracker and ctxfs service and can connect to an
externally managed ctxfs server.
Install
Section titled “Install”pip install ctxdctxd --versionConfiguration
Section titled “Configuration”ctxd endpoint statusThe command starts ctxfs for the default local socket, or checks the configured endpoint. The Unix socket does not require an API key. HTTP endpoints do.
Configure and authenticate to a network server:
ctxd login --endpoint https://ctxfs.example.net:8443ctxd endpoint set https://ctxfs.example.net:8443ctxd status --endpoint https://ctxfs.example.net:8443ctxd endpoint statuslogin prompts for the token and stores it for that normalized endpoint. Use
CTXD_CTXFS_API_KEY instead for non-interactive use. Remove the stored token
with ctxd logout --endpoint https://ctxfs.example.net:8443.
Folders
Section titled “Folders”ctxd folders add ~/Documents --name Documentsctxd folders listctxd folders remove DocumentsRemoving a root stops tracking it. It does not delete the source folder.
Tracker
Section titled “Tracker”ctxd tracker startctxd tracker statusctxd tracker stopThe tracker synchronizes configured folders while it is running. It may run with zero folders; adding folders is optional unless this machine contributes content.
Use a configured folder name as the first path segment:
ctxd files tree Documents --depth 2 --limit 100ctxd files ls Documentsctxd files glob "Documents/**/*.md" --limit 100ctxd files stat Documents/notes.mdctxd files read Documents/notes.md --max-bytes 100000ctxd files read-lines Documents/notes.md --start 20 --end 40ctxd files grep "deployment" --prefix Documents --limit 20Every listing and matching command is bounded. Inspect complete and
stopped_by in JSON output before treating a result as exhaustive.
For grep, inspect continuation_required and continuation_hint, pass
next_cursor back with --cursor to continue the same pattern and prefix, and use
--timeout-seconds to override the 2-second search deadline (0.1 to 60).
ctxd endpoint status starts the default local ctxfs process when needed and
reports the effective endpoint and health.
Run a standalone server in the foreground:
# Trusted local Unix socketctxd server serve --root ~/.ctxd/ctxfs --socket ~/.ctxd/local/ctxfs.sock
# Authenticated loopback HTTPctxd server serve --root ~/.ctxd/ctxfs --host 127.0.0.1 --port 8765
# Authenticated network HTTPSctxd server serve --root /srv/ctxfs --host 0.0.0.0 --port 8443 \ --allow-network --tls-cert /etc/ctxfs/server.crt \ --tls-key /etc/ctxfs/server.keyTCP uses bearer authentication. A non-loopback bind is rejected unless
--allow-network,--tls-cert, and --tls-key are all supplied. These are
foreground commands; ctxd does not install a background supervisor.
Server credentials
Section titled “Server credentials”Credential commands operate directly on a server data root:
ctxd keys --root /srv/ctxfs create --name reader --scope read --scope statusctxd keys --root /srv/ctxfs create --name laptop --scope submit --scope status \ --prefix local-files/ROOT_IDctxd keys --root /srv/ctxfs listctxd keys --root /srv/ctxfs rotate KEY_IDctxd keys --root /srv/ctxfs revoke KEY_IDCreation and rotation print a bearer token once. Transfer it securely; only a
verifier is retained. admin grants all capabilities and cannot be combined
with other scopes. Prefix grants apply to submit credentials; grant each
local-files/ROOT_ID stored as the folder’s prefix in the writer client’s
~/.ctxd/config.json that the tracker may update. If CTXD_CONFIG_PATH is set,
inspect that file instead. ctxd folders list prints names and source paths,
not generated prefixes.
For the default Unix-socket installation, configure MCP clients to launch the stdio bridge:
ctxd-mcpThe ctxfs server also accepts MCP JSON-RPC requests over HTTP at POST /mcp on
its configured endpoint.
Environment
Section titled “Environment”| Variable | Purpose |
|---|---|
CTXD_CONFIG_PATH | Override the CLI configuration file |
CTXD_CTXFS_SOCKET | Use ctxfs through the selected Unix socket |
CTXD_CTXFS_URL | Use ctxfs through the selected HTTP URL |
CTXD_CTXFS_API_KEY | Supply a ctxfs HTTP bearer token without storing it |