Configuration

The CLI stores configuration in a YAML file at ~/.config/clickup/config.yml. This file is created automatically during clickup auth login.

Config file reference

workspace: "1234567"
space: "89012345"
sprint_folder: "67890123"
editor: "vim"
prompt: "enabled"
aliases:
  v: task view
  s: sprint current
directory_defaults:
  /home/user/projects/api:
    space: "11111111"

Fields

Field	Type	Description
`workspace`	string	Default workspace (team) ID. Set during `auth login`.
`space`	string	Default space ID. Set via `space select`.
`sprint_folder`	string	Folder ID containing sprint lists. Auto-detected or set via `--folder`.
`editor`	string	Editor command for interactive descriptions and comments. Falls back to `$EDITOR`.
`prompt`	string	Controls interactive prompts. Set to `"enabled"` by default.
`aliases`	map	Custom command aliases. Keys are alias names, values are the full command string.
`directory_defaults`	map	Per-directory configuration overrides (see below).

Per-directory defaults

You can configure different spaces for different project directories. When you run a command from a directory that has an entry in directory_defaults, the CLI uses that directory’s space instead of the global default.

directory_defaults:
  /home/user/projects/api:
    space: "11111111"
  /home/user/projects/frontend:
    space: "22222222"

Each directory entry supports the following fields:

Field	Type	Description
`space`	string	Space ID to use when running commands from this directory.

The CLI checks the current working directory against the directory_defaults map. If a match is found, the directory-specific values override the global settings.

Custom aliases

Define aliases to create shortcuts for frequently used commands:

aliases:
  v: task view
  s: sprint current
  tl: task list --list-id 12345

GitHub link storage

The link commands store GitHub links in the task’s markdown_description field, rendered as rich text in the ClickUp UI. See the GitHub linking strategy section of the git integration guide for format details and examples.

Environment variables

Variable	Description
`CLICKUP_CONFIG_DIR`	Override the config directory path. Default: `~/.config/clickup`.
`CLICKUP_CACHE_DIR`	Override the cache directory path. Default: `~/.cache/clickup`.

When CLICKUP_CONFIG_DIR is set, the CLI reads and writes config.yml from that directory instead of the default location.

Cache directory

clickup task search keeps a local index of the workspace so it can match locally instead of paginating the API on every search. It lives in the cache directory, one file per workspace.

The cache is disposable: delete it and the next search rebuilds it. It is kept separate from the config directory for exactly that reason — the config is hand-edited and worth backing up, the cache is a rebuildable mirror.

clickup task search "auth" --refresh    # rebuild the index now
clickup task search "auth" --no-cache   # skip it for this search
clickup auth logout                     # delete it along with your credentials
rm -rf ~/.cache/clickup                 # or just remove it

If HOME is unset — some cron, CI and container environments — the cache falls back to a directory under the system temp path rather than the working directory.

Config file location

The config file path is determined as follows:

If CLICKUP_CONFIG_DIR is set, use $CLICKUP_CONFIG_DIR/config.yml.
Otherwise, use ~/.config/clickup/config.yml.

The directory is created automatically if it does not exist.