Custom fields¶

Jira custom fields are addressed by their API IDs, such as customfield_10010. Use the field cache and agent registry to map IDs to names and input shapes.

Field cache¶

jira cache fields --refresh --output=json
jira cache fields --output=json

The field cache helps completion and lets agents map human field names to customfield_NNNN keys before editing payloads.

Field-type registry¶

The CLI recognizes these custom-field types. Where a type lifts a bare value, it encodes that value into the wire shape Jira expects; the object-only types take the wire shape directly. An explicit object in the type's accepted shape is passed through unchanged.

Type	Bare input	Wire shape
`string`	`"text"`	raw value
`number`	`42` / `1.5`	raw numeric value
`date`	`"2026-05-17"`	`YYYY-MM-DD` string
`datetime`	ISO-8601 with offset	datetime string
`labels`	`["a","b"]`	array of strings
`select`	`"High"`	`{"value":"High"}`
`multiselect`	`["A","B"]`	`[{"value":"A"},{"value":"B"}]`
`user`	`"<accountId>"`	`{"accountId":"<id>"}`
`multiuser`	`["<id1>","<id2>"]`	array of `{"accountId":...}`
`group` / `multigroup`	group name(s)	`{"name":...}` / array
`components`	— (pass objects)	`[{"name":"<component>"}]`
`version` / `fixversions`	— (pass objects)	`[{"name":"<version>"}]`
`versionpicker` / `multiversionpicker`	version name(s)	`{"name":...}` / array
`projectpicker`	project key	`{"key":"<project>"}`
`parent`	— (pass the object)	`{"key":"PROJ-123"}`
`cascadingselect`	— (pass the object)	`{"value":"<top>","child":{"value":"<sub>"}}`

jira agent fieldtypes --output=json

agent fieldtypes emits the live registry as JSON, including the encoding notes above, so an agent can resolve a field shape without parsing prose.

JSON input¶

{
  "fields": {
    "customfield_10010": "Platform",
    "customfield_10011": ["frontend", "backend"]
  }
}

jira issue edit PROJ-123 --json-input fields.json --output=json

Unknown customfield types are forwarded and reported with structured warnings where the CLI cannot validate the shape locally.