Appearance actions

5 actions. Each action calls the same API route with the same scopes on every surface.

appearance_get

Get Appearance settings.

Route	GET /api/v1/appearance
Tool name	calternal_api_appearance_get
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

calternal action run appearance_get --input '{}' --json

appearance_put

Update Appearance settings. Body fields: auto_scheme, background, background_assignment, backgrounds, fonts, initialize_auto_scheme..

Route	PUT /api/v1/appearance
Tool name	calternal_api_appearance_put
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
auto_scheme	object or null	no
background	object or null	no
background_assignment	object or null	no
backgrounds	object | null	no	Per-family light and dark backgrounds.
fonts	object or null	no
initialize_auto_scheme	object or null	no

calternal action run appearance_put --input '{}' --confirm --json

appearance_unsplash_search

Search background images Continuation: Request the next declared page until pages is reached..

Route	GET /api/v1/appearance/unsplash/search
Tool name	calternal_api_appearance_unsplash_search
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

query

Field	Type	Required	Description
page	integer, int32 (0–)	no
q	string	yes

calternal action run appearance_unsplash_search --input '{"query":{"q":"<q>"}}' --json

appearance_unsplash_select

Select a background image. Body fields: family, scheme..

Route	POST /api/v1/appearance/unsplash/{photo_id}
Tool name	calternal_api_appearance_unsplash_select
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

path

Field	Type	Required	Description
photo_id	string	yes

body

Field	Type	Required	Description
family	"paper" | "meridian" | "bloom" | "mono" | "solarized" | "catppuccin" | "rose-pine" | "ayu" | "github" | "one" | "tokyo-night" | "gruvbox" | "everforest" | "kanagawa" | "dracula" | "nord"	yes	Stable family keys used for backgrounds shared between devices.
scheme	"light" | "dark"	yes	Family and scheme target for a server-downloaded Unsplash photo.

calternal action run appearance_unsplash_select --input '{"path":{"photo_id":"<photo_id>"}}' --confirm --json

appearance_unsplash_thumbnail

Get a background image thumbnail.

Route	GET /api/v1/appearance/unsplash/images/{photo_id}
Tool name	calternal_api_appearance_unsplash_thumbnail
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response base64

path

Field	Type	Required	Description
photo_id	string	yes

calternal action run appearance_unsplash_thumbnail --input '{"path":{"photo_id":"<photo_id>"}}' --json