jq keys : List the Keys of an Object

jq keys returns the keys of an object as a sorted array, or the indices of an array.

When you do not know the shape of an API response yet, keys is the fastest way to see what fields a step can rely on.

What it does

keys takes an object and returns its keys as an array, sorted in unicode order. On an array it returns the integer indices. keys_unsorted returns object keys in their original insertion order.

Common usage

Terminal

# what fields does this API return?
gh api repos/cli/cli --jq 'keys'
# keep original order
curl -s https://api.github.com/repos/cli/cli | jq 'keys_unsorted'
# keys of a nested object
jq '.permissions | keys' repo.json

Functions

Function	What it does
keys	Sorted array of object keys (or array indices)
keys_unsorted	Object keys in insertion order
values	Array of the object or array values
has("k")	Test whether a key is present

Common errors in CI

"jq: error: null (null) has no keys" means you ran keys on a missing field that evaluated to null; check the path. "jq: error: string (\"...\") has no keys" means the input is a scalar string, often because the API returned an error message rather than the JSON object you expected.

Related guides

jq to_entries and from_entries : Object/Pairsjq to_entries converts an object into {key,value} pairs and from_entries rebuilds it. Reference for looping a… jq has() : Test Whether a Key Existsjq has("key") returns true when an object contains a key or an array has an index. Reference for guarding opt… jq .[] : Iterate Over a JSON Array or ObjectThe jq .[] operator streams each element of an array or each value of an object. Reference for iterating gh a… jq length : Count Elements or String Sizejq length returns array size, object key count, or string length. Reference for counting gh api results in CI…