jqの起動

jqのフィルターはJSONデータのストリームを処理します。jqへの入力は、空白で区切られたJSON値の列として解析され、指定したフィルターへ1つずつ渡されます。フィルターの出力は、改行で区切られたJSONデータの列として標準出力に書き出されます。

最も単純で、最もよく使われるフィルター（jqプログラム）は . です。これは恒等演算子で、jq処理系への入力をそのまま出力ストリームへコピーします。jq処理系は既定で入力ストリームからJSONテキストを読み取り、出力を整形するため、. プログラムの主な用途は入力の検証と整形です。jqのプログラミング言語には豊富な機能があり、検証や整形以外にもはるかに多くのことができます。

注意：シェルの引用規則に気を配ることが大切です。一般則として、jqプログラムは常に引用符で囲むのが最善です（Unixシェルでは一重引用符を使います）。jqで特別な意味を持つ文字の多くは、シェルのメタ文字でもあるためです。たとえば、jq "foo" はほとんどのUnixシェルで失敗します。これは jq foo と同じになり、通常は foo is not defined という理由で失敗するからです。Windowsコマンドシェル（cmd.exe）では、-f program-file オプションの代わりにコマンド行でjqプログラムを指定する場合、プログラムを二重引用符で囲むのが最善ですが、その場合はjqプログラム内の二重引用符をバックスラッシュでエスケープする必要があります。Powershell（powershell.exe）またはPowershell Core（pwsh/pwsh.exe）では、jqプログラムを一重引用符で囲み、プログラム内の二重引用符をバックスラッシュでエスケープ（\"）してください。

Unixシェル：jq '.["foo"]'
Powershell：jq '.[\"foo\"]'
Windowsコマンドシェル：jq ".[\"foo\"]"

注意：jqではユーザー定義関数を使えますが、すべてのjqプログラムにはトップレベルの式が必要です。

コマンド行オプションを使って、jqによる入出力の読み書きの方法を変更できます。

--null-input / -n:

入力を一切読み取りません。代わりに、null を入力としてフィルターを1回実行します。jqを簡単な計算機として使う場合や、JSONデータを一から構築する場合に便利です。

--raw-input / -R:

入力をJSONとして解析しません。代わりに、テキストの各行を文字列としてフィルターへ渡します。--slurp と組み合わせると、入力全体を1つの長い文字列としてフィルターへ渡します。

--slurp / -s:

入力中のJSONオブジェクトごとにフィルターを実行する代わりに、入力ストリーム全体を大きな配列へ読み込み、フィルターを1回だけ実行します。

--compact-output / -c:

jqは既定でJSON出力を整形します。このオプションを使うと、各JSONオブジェクトを1行にまとめ、よりコンパクトに出力します。

--raw-output / -r:

このオプションを使うと、フィルターの結果が文字列の場合、引用符付きのJSON文字列に整形せず、そのまま標準出力に書き出します。jqフィルターをJSONを使わないシステムと連携させる場合に便利です。

--raw-output0:

-r と同様ですが、各出力の後に改行ではなくNULを出力します。出力する値に改行が含まれる場合に便利です。出力値にNULが含まれる場合、jqは0以外のコードで終了します。

--join-output / -j:

-r と同様ですが、各出力の後に改行を出力しません。

--ascii-output / -a:

jqは通常、ASCII以外のUnicodeコードポイントをUTF-8で出力します。入力でエスケープシーケンス（"\u03bc"など）を使って指定した場合も同様です。このオプションを使うと、ASCII以外の各文字を対応するエスケープシーケンスに置き換え、ASCIIだけで出力するよう強制できます。

--sort-keys / -S:

各オブジェクトのフィールドを、キーをソートした順序で出力します。

--color-output / -C と --monochrome-output / -M:

jqは既定で、端末に書き出す場合にJSONを色付きで出力します。-C を使うと、パイプやファイルに書き出す場合でも色付きの出力を強制でき、-M で色を無効にできます。環境変数 NO_COLOR が空でない場合、jqは既定で色付きの出力を無効にしますが、-C で有効にできます。

色は環境変数 JQ_COLORS で設定できます（後述）。

--tab:

インデントの各段階で、2つの空白の代わりにタブを使います。

--indent n:

指定した数の空白（最大7個）でインデントします。

--unbuffered:

JSONオブジェクトを出力するたびに、出力をフラッシュします（遅いデータソースをパイプでjqへ渡し、jqの出力をさらに別の場所へパイプで渡す場合に便利です）。

--stream:

入力をストリーミング方式で解析し、パスと葉の値（スカラー、および空の配列や空のオブジェクト）からなる配列を出力します。たとえば、"a" は [[],"a"] になり、[[],"a",["b"]] は [[0],[]]、[[1],"a"]、[[2,0],"b"] になります。

非常に大きな入力の処理に便利です。フィルタリング、および reduce と foreach の構文と組み合わせて使うと、大きな入力を逐次的に集約できます。

--stream-errors:

--stream と同様ですが、不正なJSON入力に対して、第1要素がエラー、第2要素がパスの配列値を生成します。たとえば、["a",n] は ["Invalid literal at line 1, column 7",[1]] を生成します。

--stream を暗黙に有効にします。--stream を使い、--stream-errors を付けなかった場合、不正なJSON入力に対してエラー値は生成されません。

--seq:

jqの入出力でJSONテキストを区切るために、MIMEタイプ application/json-seq の方式を使います。つまり、出力の各値の前にASCIIのRS（レコード区切り）文字を、各出力の後にASCIIのLF（改行）を出力します。解析に失敗した入力JSONテキストは無視されますが警告が出され、次のRSまでの後続入力はすべて破棄されます。このモードでは、--seq オプションを付けずに実行したjqの出力も解析できます。

-f / --from-file:

awkの-fオプションのように、コマンド行ではなくファイルからフィルターを読み取ります。このオプションにより、フィルター引数はプログラムのソースではなくファイル名として解釈されます。

-L directory / --library-path directory:

モジュールの検索リストの先頭に directory を追加します。このオプションを使うと、組込みの検索リストは使われません。後述のモジュールの節を参照してください。

--arg name value:

このオプションは、事前定義された変数として値をjqプログラムへ渡します。--arg foo bar を指定してjqを実行すると、プログラム内で $foo を使え、その値は "bar" になります。value は文字列として扱われるため、--arg foo 123 は $foo に "123" を束縛します。

名前付き引数は、jqプログラム内で $ARGS.named としても使えます。名前が有効な識別子でない場合、それにアクセスするにはこの方法しかありません。

--argjson name JSON-text:

このオプションは、JSONエンコードされた値を事前定義された変数としてjqプログラムへ渡します。--argjson foo 123 を指定してjqを実行すると、プログラム内で $foo を使え、その値は 123 になります。

--slurpfile variable-name filename:

指定したファイル内のすべてのJSONテキストを読み取り、解析されたJSON値の配列を指定したグローバル変数へ束縛します。--slurpfile foo bar を指定してjqを実行すると、プログラム内で $foo を使えます。その値は、bar という名前のファイル内の各テキストに対応する要素を持つ配列です。

--rawfile variable-name filename:

指定したファイルを読み取り、その内容を指定したグローバル変数へ束縛します。--rawfile foo bar を指定してjqを実行すると、プログラム内で $foo を使え、その値は bar という名前のファイル内のテキストを内容とする文字列になります。

--args:

残りの引数は、文字列の位置引数として扱われます。jqプログラム内で $ARGS.positional[] として使えます。

--jsonargs:

残りの引数は、JSONテキストの位置引数として扱われます。jqプログラム内で $ARGS.positional[] として使えます。

--exit-status / -e:

jqの終了ステータスは、最後の出力値が false でも null でもない場合に0、最後の出力値が false または null の場合に1、有効な結果が一度も生成されなかった場合に4になります。通常、使用方法の問題またはシステムエラーがあった場合には2、jqプログラムのコンパイルエラーがあった場合には3、jqプログラムが実行された場合には0で終了します。

終了ステータスを設定する別の方法として、組込み関数 halt_error もあります。

--binary / -b:

WSL、MSYS2、Cygwinを使うWindowsユーザーは、ネイティブのjq.exeを使う場合、このオプションを指定してください。指定しないと、jqは改行（LF）を復帰と改行の組（CRLF）へ変換します。

--version / -V:

jqのバージョンを出力し、0で終了します。

--build-configuration:

jqのビルド設定を出力し、0で終了します。この出力には、サポート対象として保証された形式や構造がなく、将来のリリースで予告なく変わる可能性があります。

--help / -h:

jqのヘルプを出力し、0で終了します。

--:

引数の処理を終了します。残りの引数はオプションとして解釈されません。

--run-tests [filename]:

指定したファイルまたは標準入力内のテストを実行します。指定するオプションの最後に置く必要があり、それより前のオプションすべてに従うわけではありません。入力は、コメント行、空行、プログラム行と、それに続く1行の入力、期待する出力の数だけの出力行（出力1つにつき1行）、最後の空行で構成されます。コンパイル失敗のテストは、%%FAIL だけを含む行、コンパイルするプログラムを含む行、実際のエラーと比較するエラーメッセージを含む行の順で始まります。

このオプションは後方互換性を保たずに変更される可能性があるので、注意してください。