redis-cliは、Redisにコマンドを送るための公式のコマンドラインツールで、既定では127.0.0.1の6379番ポートへ接続します。この記事では、Redis公式ドキュメントとAWSのガイドをもとに、redis-cliの入手方法、ホスト・ポート・パスワード・ACLユーザーの指定、TLS接続の書き方を整理しました。後半では、本番でKEYSを打たずに--scanでキーを探す手順、--bigkeysや--latencyによる調査、よく使うコマンドの一覧を実行例で示します。最後に、本番環境でredis-cliを誰にどこまで開放するかの判断を言い切ります。
まとめ:redis-cliは接続の指定と本番で打ってよいコマンドの線引きで使う
redis-cliの使い方は、接続の指定と「本番で打ってよいコマンド」の線引きの2つに分けると迷いません。接続は-h・-p・-nでホスト・ポート・DB番号を決め、パスワードはシェル履歴に残る-aではなく環境変数REDISCLI_AUTHか--askpassで渡します。暗号化が必須の環境では--tlsを付けます。
本番ではKEYS *とMONITORを打ちません。キーを探すならredis-cli --scan --pattern、大きいキーは--bigkeys、遅延は--latencyが担当です。
チームで運用するなら、危険なコマンドを外した読み取り専用のACLユーザーを配り、サーバー側で事故を防ぎます。大量削除や移行のような書き込みは、対話モードの手打ちではなくレビュー済みのスクリプトで流してください。
redis-cliの入手と起動、対話モードとワンライナーの2つの使い方
redis-cliはRedis本体と同じリポジトリで開発されており、2026年11月時点の最新安定版は8.10.3(10月26日公開)です。Redisそのものの仕組みやデータ型はRedisとは:仕組みとデータ型・Redis 8.10系の新機能とライセンス、Dockerで動かす手順で扱っているため、ここではツールとしての使い方に絞ります。
スタンドアロン版インストーラ・Docker・本体同梱から選ぶ入手方法
接続先のRedisが別サーバーにあり、手元にはクライアントだけ欲しい場合は、Install redis-cliの公式スクリプトが手軽です。静的リンクされた単体バイナリを取得し、SHA-256のチェックサムを検証してから/usr/local/binに置きます。
# 最新の安定版を入れる(Linux・macOS、x86_64とarm64)
curl -fsSL https://packages.redis.io/redis-cli/install.sh | sh
# 版を固定したい場合
curl -fsSL https://packages.redis.io/redis-cli/install.sh | REDIS_CLI_VERSION=8.8.0 sh
redis-cli --version
このスクリプトはネイティブのWindowsでは動かないため、WindowsではWSLかDockerを使います。Docker Hubの公式redisイメージにはredis-cliが同梱されており、サーバーにRedis本体を入れた場合も同時に入ります。Docker上のRedisの永続化と認証の設定はRedisをDockerで動かす手順:compose.yamlでの永続化・redis.conf・パスワード設定で解説しています。
対話モードのプロンプト表示とHELP・履歴・補完で打ち間違いを減らす
引数なしでredis-cliを起動すると対話モードに入り、プロンプトに127.0.0.1:6379>の形で接続先が出ます。DB番号0以外を選ぶと127.0.0.1:6379[2]>のように番号が付くため、どのDBを触っているかを画面で確かめられます。
コマンド名はTABで補完でき、入力後には引数のヒントが出ます。HELP SCANで個別の書式、HELP @stringで分類ごとの一覧を引けます。履歴はホームディレクトリの.rediscli_historyに残る仕様です。8.10.3のredis-cliのソースでは、AUTHやACL SETUSERのように秘密情報を含むコマンドは履歴ファイルに書かない処理になっています。共有の踏み台で履歴そのものを残したくなければ、環境変数REDISCLI_HISTFILEに/dev/nullを指定して止めます。
引数で1回だけ実行する形と–rawで出力を他コマンドへ渡す形
コマンドを引数に並べると、1回だけ実行して結果を標準出力に返します。Redis CLIのドキュメントによると、出力先が端末でないときは(integer)のような型表示を外した「rawモード」に自動で切り替わります。
$ redis-cli INCR mycounter
(integer) 7
# ファイルやパイプへ渡すと型表示が消える
$ redis-cli INCR mycounter > /tmp/output.txt
# 同じコマンドを1秒おきに繰り返す(-r -1 で無限)
$ redis-cli -r -1 -i 1 INFO memory | grep used_memory_human
シェルスクリプトから呼ぶときは、コマンドの失敗時に終了コードを返す-eを付けます。付けないと、Redisがエラーを返してもredis-cli自体は正常終了し、後続の処理が止まりません。
接続先ホスト・ポート6379・パスワード・ACLユーザーを指定する接続手順
接続でつまずく原因は、指定の漏れか、パスワードの渡し方です。オプションの意味を公式の説明どおりに押さえます。
-hと-pと-nでホスト・ポート・DB番号を指定する基本の接続コマンド
既定の接続先は127.0.0.1の6379番で、別のホストは-h、ポートは-p、DB番号は-nで変えます。-tを付けると接続タイムアウトを秒で指定でき、既定値の0は無制限です。
# ホストとポートを指定して疎通を確かめる
redis-cli -h redis15.localnet.org -p 6390 PING
# DB番号1に対して実行する
redis-cli -n 1 INCR a
# Unixソケットで接続する(ホストとポートより優先。パスは環境による)
redis-cli -s /var/run/redis/redis.sock PING
接続情報を1本にまとめたい場合は、-uにredis://で始まるURIを渡せます。TLSならスキームをredissにし、ユーザー名を使わない認証ではユーザー名に指定する値はdefaultです。Connection refusedが返るときは、ポート番号、サーバーが127.0.0.1だけで待ち受けていないか、ファイアウォールやセキュリティグループの順に確かめます。
-aを避けREDISCLI_AUTHと–askpassでパスワードを渡す理由
-aは手軽ですが、パスワードがシェルの履歴に残り、実行中はプロセス一覧からも見えます。redis-cliは-aを使うと警告を出し、公式ドキュメントで推奨されているのも環境変数REDISCLI_AUTHで渡す方法です。両方を指定すると-aが優先され、--askpassを付けた場合はどちらも無視してマスク付きの入力を求めます。
# 環境変数で渡す(read で読み込めば履歴に値が残らない)
read -rs REDISCLI_AUTH && export REDISCLI_AUTH
redis-cli -h redis.internal.example PING
# その場でマスク入力させる
redis-cli -h redis.internal.example --askpass
環境変数なら、パスワードに"や'が含まれていてもエスケープを考えずに済みます。対話モードでAUTHを打つ場合は、引用符を\"の形でエスケープする必要があります。
–userで渡すACLユーザーとNOPERMエラーが出たときの確認手順
RedisはRedis 6でACLを導入し、AUTH ユーザー名 パスワードの2引数の形を使えるようにしました。ACLのドキュメントによると、パスワードだけを渡す従来の形はdefaultユーザーとしての認証になります。redis-cliでは--userでユーザー名を渡し、パスワードは--askpassかREDISCLI_AUTHと組み合わせます。
$ redis-cli -h redis.internal.example --user support --askpass
redis.internal.example:6379> ACL WHOAMI
"support"
redis.internal.example:6379> SET cached:1234 zap
(error) NOPERM this user has no permissions to run the 'set' command
NOPERMは、そのユーザーにコマンドかキーの権限が無いという意味です。まずACL WHOAMIで意図したユーザーで入れているかを確かめ、権限の中身は管理者がACL GETUSER supportで確認します。
TLS必須のRedisとElastiCacheへredis-cliで暗号化接続する設定
redis-cliの既定の接続方式は、平文のTCPです。TLSのドキュメントによると、TLSはRedis 6から使えるオプション機能で、make BUILD_TLS=yesのようにビルド時に有効にします。--tlsが使えないredis-cliは、TLS対応でビルドされたものに入れ替えます。
–tlsと–cacertで自己管理Redisへ接続し、相互TLSなら証明書を足す
サーバー証明書の検証に使うCAを--cacert(ディレクトリなら--cacertdir)で渡し、--tlsを付けて接続します。
# サーバー証明書をCAで検証して接続する
redis-cli -h redis.internal.example -p 6379 --tls --cacert ./ca.crt PING
# 相互TLS:クライアント証明書と秘密鍵も渡す(公式の例)
redis-cli --tls \
--cert ./tests/tls/redis.crt \
--key ./tests/tls/redis.key \
--cacert ./tests/tls/ca.crt
見落としやすいのは、サーバー側の既定が相互TLSである点です。クライアント証明書を配らない運用なら、サーバーの設定でtls-auth-clients noにします。port 0とtls-port 6379を組み合わせると、6379番をTLS専用にする構成が可能です。TLSを通すと1インスタンスあたりのスループットは下がるため、性能試験は本番と同じTLS設定で行います。
ElastiCacheの転送中暗号化に–tlsと-cで接続するときの注意点
AWSの接続ガイドは、Amazon Linux 2023でsudo dnf install valkey -yを実行し、TLS対応のvalkey-cliで接続する手順を載せています。オプションはredis-cliと共通で、redis6パッケージを入れた場合のコマンド名はredis6-cliです。
# 転送中暗号化と認証が有効なキャッシュへ接続する
valkey-cli -h プライマリエンドポイント --tls --askpass -p 6379
# クラスターモード有効の設定エンドポイントには -c を足す
valkey-cli -c -h 設定エンドポイント --tls --askpass -p 6379
-cを付けないと、別のシャードにあるキーを触ったときにMOVEDのリダイレクトを追わずにエラーで終わります。TLS非対応のクライアントしか使えない環境向けに、stunnelでローカルにトンネルを作る方法も同じページにあります。ElastiCacheとMemoryDBの選び分けはAWSでRedisを使う方法:ElastiCache・MemoryDB・EC2の選び分けと接続手順にまとめました。
KEYSでなくSCANを使う理由と、redis-cli –scanでキーを安全に探す手順
「redis keys」で調べる人の多くは、キーの一覧を出したい場面にいます。開発環境ならKEYSで構いません。本番では話が変わります。
100万キーで40ミリ秒でも本番でKEYSを打たないブロッキングの理由
KEYSのドキュメントは、計算量をキー数NのO(N)とし、入門機のノートPCで100万キーを40ミリ秒で走査できると書いています。そのうえで、大きなDBに対して実行すると性能を損なうおそれがあるため本番では細心の注意を払い、アプリケーションのコードでは使わないよう警告しています。
問題は、走査が終わるまでサーバーが他のコマンドを処理しないことです。Redis CLIのドキュメントもKEYS *がサーバーをブロックすると明記しています。同じ速度なら1億キーで単純計算4秒、その間はキャッシュの読み取りもセッションの確認も待たされます。KEYSはACLの@dangerous分類にも入っており、権限で禁止できる側のコマンドです。
–scanと–patternと-iで負荷を抑えて該当キーを数える・消す
--scanは内部でSCANを少しずつ呼ぶため、サーバーをブロックしません。-iでSCANの呼び出しごとに待ち時間を入れると、処理は遅くなる代わりに負荷をさらに下げられます。
# パターンに一致するキーの件数を数える
redis-cli --scan --pattern 'session:*' | wc -l
# 先頭20件だけ見る(SCANごとに0.01秒待つ)
redis-cli --scan --pattern 'session:*' -i 0.01 | head -20
# 一致したキーを100件ずつUNLINKで消す(先に件数を確かめてから)
redis-cli --scan --pattern 'tmp:import:*' -i 0.01 | xargs -L 100 redis-cli UNLINK
削除にDELではなくUNLINKを使うのは、メモリの回収を別スレッドで行い、大きなキーでもブロックしないためです。パスワードはREDISCLI_AUTHで渡しておけば、パイプの両側のredis-cliが同じ認証で動きます。キー名に空白や引用符を含む場合、xargsで分割が崩れるのでこの方法は使えません。
SCANの重複返却・空ページ・COUNTはヒントという3つの仕様
アプリケーションからSCANを直接呼ぶ場合は、SCANのドキュメントにある仕様を前提に組みます。開始から終了まで存在したキーは必ず1回は返りますが、同じキーが複数回返ることがあり、処理は何度適用しても同じ結果になる形にします。
> scan 0 MATCH *11*
1) "288"
2) 1) "key:911"
> scan 288 MATCH *11*
1) "224"
2) (empty list or set)
MATCHは取り出した後に適用されるため、一致が少ないと空の結果が続きます。返ってきたカーソルが0になるまでが1周で、空だからといって途中で止めてはいけません。COUNTは既定10の「1回あたりの作業量のヒント」で件数の保証ではなく、型で絞るTYPEはRedis 6.0から使えます。
–bigkeysや–latencyで本番Redisの詰まりを調べる運用コマンド
「Redisが遅い」「メモリが急に増えた」という相談では、redis-cliの特殊モードで当たりを付けられます。どれもアプリを止めずに実行できますが、負荷のかけ方に差があります。
–bigkeys・–memkeys・–keystatsで大きいキーを見つける手順
# 型ごとに要素数の多いキーを探す(SCAN 100回ごとに0.1秒待つ)
redis-cli --bigkeys -i 0.1
# メモリを多く使うキーを探す
redis-cli --memkeys
# 両方をまとめて分布も出す。上位20件を表示
redis-cli --keystats --top 20
3つともSCANで走査するため、稼働中のサーバーでも実行できると公式は説明しています。--bigkeysは要素数、--memkeysはバイト数で比べる違いがあり、メモリ逼迫の調査で確認する対象は後者です。--keystatsを途中で止めた場合は、--cursorで続きから再開できます。--bigkeysと--memkeysはClusterのレプリカでも動くので、プライマリの負荷が気になる場合の実行先はレプリカです。
–latencyと–statで遅延と接続数を毎秒追うときの読み方
# 30秒ごとに区切って遅延の最小・最大・平均を記録する
redis-cli --latency-history -i 30
# キー数・メモリ・クライアント数・リクエスト数を毎秒表示する
redis-cli --stat
# Redisサーバー上で実行し、OS自体の遅延を60秒測る(接続はしない)
redis-cli --intrinsic-latency 60
--latencyは毎秒100回PINGを送り、ミリ秒で集計します。平均はredis-cli側のスケジューラ遅延の分だけ大きめに出るため、数ミリ秒以上の山を見るための道具として捉えてください。--latency-historyは既定15秒ごとに集計をやり直します。--intrinsic-latencyは仮想化基盤を含むマシン自体の遅延を測るもので、Redisが動くサーバー上で実行しないと意味がありません。遅延の原因をSLOWLOGとLATENCY DOCTORで切り分ける手順はRedisのシングルスレッドとは:io-threadsの設定とSLOWLOGで遅いコマンドを切り分ける手順で解説しています。
調査でよく使うコマンド一覧と本番で打たないMONITOR・FLUSHALL
対話モードで状態を調べるときに使う、読み取り系のコマンドです。データ型ごとのSETやGETの使い方はKVS(キーバリューストア)とは:Redisで動かして分かる仕組みとRDBとの使い分けで扱っています。
| 調べたいこと | コマンド |
|---|---|
| キーの総数 | DBSIZE |
| キーの型 | TYPE キー |
| 残りの有効期限 | TTL キー |
| 1キーのメモリ量 | MEMORY USAGE キー |
| メモリ全体の使用量 | INFO memory |
| 遅いコマンドの履歴 | SLOWLOG GET 10 |
| 接続中のクライアント | CLIENT LIST |
| 設定値の確認 | CONFIG GET maxmemory |
本番で打たないのはKEYS *、全データを消すFLUSHALLとFLUSHDB、そしてMONITORです。MONITORのドキュメントには、1つのMONITORクライアントでスループットが50%以上落ちたベンチマークが載っています。キャッシュの当たり率を試す--lru-testも、公式が本番インスタンスでの使用を禁じています。
本番Redisでredis-cliを開放する条件と、開発者に打たせない場面の判断
redis-cliは、接続できればFLUSHALLも1行で通るツールです。そこで「誰が、どの権限で、どこから」打てるかを先に決めます。
読み取り専用ACLユーザーを配り-@dangerousで事故コマンドを封じる
開発者や保守担当に本番を見せる条件は、読み取りと接続系だけを許し、@dangerous分類を外したユーザーを使うことです。INFOも@dangerousに入るため、調査で要るなら後から足します。
# 管理者で実行する。パスワードは ACL GENPASS で生成した値を使う
> ACL GENPASS
> ACL SETUSER support on >生成したパスワード ~* +@read +@connection -@dangerous +info
# aclfile を使っていれば ACL SAVE、redis.conf 管理なら CONFIG REWRITE で保存
> ACL SAVE
注意点は、キーパターンでは全体を消すコマンドを止められないことです。ACLのドキュメントは、~tenant1:* +@allのユーザーでもFLUSHALLでDB全体を消せると明記し、-flushall -flushdb -swapdbで明示的に外すよう求めています。マネージドサービスでは設定系コマンドが制限されることがあるため、サービス側のユーザー管理で同じ権限を作ります。
調査はレプリカと踏み台に限り、大量削除や移行を手作業にしない判断
次の作業は、本番のプライマリに対してredis-cliの手打ちでは行いません。
- パターン指定での大量削除や、キー名の付け替え
- 型の変更やTTLの一括付与を伴うデータ移行
--bigkeysなどの全キー走査(レプリカがあればそちらで行う)
削除や移行はスクリプトにして、まず--scanとwc -lで対象件数を確かめ、レビューを通してから流します。事前にredis-cli --rdbでRDBを手元に取っておき、終了コードが0以外なら作業に進みません。キーの命名やTTLの設計が場当たりで、毎回こうした手作業が発生しているなら、Redisを含むデータ層の設計を見直す時期です。データベース設計・移行支援では、現行のキー構成とアクセス傾向の棚卸しから相談を受けています。
よくある質問
redis-cliについて検索されることの多い質問に答えます。
redis-cliのデフォルトのポート番号と接続先はどこですか?
オプションを付けずに起動すると、127.0.0.1の6379番ポートへ接続します。別のサーバーには-hでホスト名かIPアドレス、-pでポート番号を指定してください。TLSを有効にしたサーバーではtls-port 6379のように同じ6379番をTLS用に割り当てる構成も多く、その場合は--tlsを足すだけで接続できます。Sentinelは既定で26379番を使うため、6379番とは別に扱います。Sentinelで冗長化する手順はRedisの冗長化:レプリケーションとSentinelで自動フェイルオーバーを組む設定例とElastiCache Multi-AZとの比較を参照してください。
Windowsでredis-cliだけを使うにはどうすればよいですか?
公式のスタンドアロン版インストーラはLinuxとmacOS向けで、ネイティブのWindowsでは動きません。公式ドキュメントが案内している方法は2つで、WSL上でインストーラを実行するか、Dockerの公式redisイメージに同梱されたredis-cliを使います。GUIで中身を確かめたい場合は、DBeaverとは?インストール・日本語化・接続設定と無料版の範囲のような汎用クライアントも選択肢です。
redis-cliで全キーを一覧表示するにはどうしますか?
開発環境ならKEYS *で一覧が出ます。本番やキー数の多い環境では、サーバーをブロックしないredis-cli --scanを使い、--pattern 'user:*'のように絞り込んでください。件数だけ知りたいならDBSIZEで総数、パターンごとの件数は--scanの出力をwc -lで数えれば分かります。SCANは同じキーを複数回返すことがある点に注意してください。
redis-cliでパターンに一致するキーをまとめて削除できますか?
パターンを受け取って削除する単独のコマンドはありません。redis-cli --scan --pattern 'tmp:*' | xargs -L 100 redis-cli UNLINKのように、SCANの結果をUNLINKに渡します。実行前に同じパターンでwc -lを取り、想定どおりの件数かを確かめましょう。キー名に空白を含む場合は分割が崩れるため、スクリプトでSCANとUNLINKを組みます。
redis-cliでデータベース(DB番号)を切り替えるには?
起動時に-n 2のように指定するか、対話モードでSELECT 2を実行します。0以外を選ぶとプロンプトが127.0.0.1:6379[2]>に変わるので、誤ったDBへの書き込みを防ぐための目印として確認してください。接続が切れて自動で再接続した場合、redis-cliは最後に選んだDB番号を選び直しますが、MULTI中のトランザクションなど他の状態は失われます。
関連記事
- Redisとは:仕組みとデータ型・Redis 8.10系の新機能とライセンス、Dockerで動かす手順:Redis本体の仕組みと版・ライセンス
- KVS(キーバリューストア)とは:Redisで動かして分かる仕組みとRDBとの使い分け:データ型ごとの基本コマンド
- AWSでRedisを使う方法:ElastiCache・MemoryDB・EC2の選び分けと接続手順:AWS上の構成と接続
- GitHub Actionsのサービスコンテナ(services)|DB・Redisを立てる結合テストと起動待ちの設計:CIでredis-cliを使った起動待ち
- DBeaverとは?インストール・日本語化・接続設定と無料版の範囲:GUIでRedisの中身を見る方法