# Nushell 業務運用マニュアル

## 目次

**【基本操作】**
1. [システム概要](#1-システム概要)
2. [起動・終了手順](#2-起動終了手順)
3. [メインREPL画面](#3-メインrepl画面)

**【業務フローに沿った機能】**
4. [【STEP1】コマンド入力・実行](#4-step1コマンド入力実行)
5. [【STEP2-3】補完機能の活用](#5-step2-3補完機能の活用)
6. [【STEP3-4】データ探索（Explore）](#6-step3-4データ探索explore)
7. [【STEP4-5】スクリプト作成・実行](#7-step4-5スクリプト作成実行)

**【サポート機能】**
8. [ヘルプ機能](#8-ヘルプ機能)
9. [履歴機能](#9-履歴機能)
10. [設定カスタマイズ](#10-設定カスタマイズ)

**【運用ガイド】**
11. [日常業務の流れ](#11-日常業務の流れ)
12. [よくある質問と対処法](#12-よくある質問と対処法)
13. [トラブルシューティング](#13-トラブルシューティング)

---

## 1. システム概要

### 1.1 Nushellとは

Nushell（Nu）は、構造化データを扱うことに特化した新しいタイプのシェルです。従来のシェル（bash、zshなど）がテキストストリームを扱うのに対し、Nushellはデータを構造化された形式（テーブル、リスト、レコードなど）で操作し、パイプラインを通じてデータを変換・フィルタリングします。

**主な特徴：**
- テーブル形式でデータを扱い、視覚的にわかりやすい出力
- パイプライン処理で複雑なデータ処理も簡潔に記述
- 豊富な組み込みコマンド群
- 強力な補完機能とシンタックスハイライト
- JSON、YAML、CSV、TOMLなど様々なデータ形式をネイティブにサポート

### 1.2 本システムで行う主要業務

本システムは、主に以下の業務を支援します：

| 業務カテゴリ | 具体的な業務内容 |
|------------|----------------|
| **コマンド実行** | シェルコマンドの入力・実行、パイプライン処理、スクリプト実行 |
| **データ処理** | テーブルデータのフィルタリング、ソート、変換、集計 |
| **ファイル操作** | ファイル・ディレクトリの操作、各種フォーマットの読み書き |
| **システム管理** | プロセス管理、環境変数操作、システム情報取得 |
| **開発支援** | LSP統合によるエディタ連携、スクリプト開発、デバッグ |

### 1.3 業務フロー概要

本システムにおける業務は、以下の流れで進行します：

```
+---------------------------------------------------------------------+
|                        業務フロー                                    |
+---------------------------------------------------------------------+
|                                                                     |
|  【STEP 1】コマンドの入力                                            |
|      - REPLにコマンドを入力                                          |
|      - Tab補完でコマンド名やパスを補完                                |
|      ↓                                                              |
|  【STEP 2】入力支援機能の活用                                         |
|      - シンタックスハイライトでコマンドを確認                           |
|      - ヘルプ補完でコマンドの使い方を確認                               |
|      ↓                                                              |
|  【STEP 3】コマンドの実行                                             |
|      - Enterキーでコマンドを実行                                      |
|      - 結果がテーブル形式で表示                                        |
|      ↓                                                              |
|  【STEP 4】結果の確認・探索                                           |
|      - 出力結果を確認                                                 |
|      - 必要に応じてexploreで詳細探索                                   |
|      ↓                                                              |
|  【STEP 5】次の操作へ                                                 |
|      - パイプラインで次の処理へつなげる                                 |
|      - 結果をファイルに保存                                           |
|                                                                     |
+---------------------------------------------------------------------+
```

**役割別の業務概要：**

| 役割 | 主な業務 |
|------|---------|
| **一般ユーザー** | コマンド実行、ファイル操作、データ処理、スクリプト実行 |
| **開発者** | スクリプト開発、LSP連携、プラグイン活用、カスタマイズ |
| **システム管理者** | システム情報取得、プロセス管理、環境設定 |

### 1.4 主な機能

| 機能 | 説明 | 業務フローでの位置 |
|------|------|------------------|
| REPL | 対話型シェル環境でコマンドを入力・実行 | STEP 1-3 |
| 補完機能 | コマンド名、パス、変数等の自動補完 | STEP 1-2 |
| シンタックスハイライト | 入力中のコマンドを色分け表示 | STEP 2 |
| ヘルプ機能 | コマンドの使い方を表示 | 随時参照 |
| Explore | データをインタラクティブに探索 | STEP 4 |
| 履歴機能 | 過去のコマンドを検索・再利用 | STEP 1 |
| LSP連携 | エディタとの統合機能 | STEP 5（開発時） |

### 1.5 ユーザー種別

システムには以下のユーザー種別があります：

| ユーザー種別 | 説明 |
|-------------|------|
| 一般ユーザー | Nushellをシェルとして日常的に使用するユーザー |
| 開発者 | Nushellスクリプトを開発するユーザー |
| システム管理者 | システム管理タスクにNushellを使用するユーザー |

### 1.6 対応環境

**対応OS：**
- Windows 10/11
- macOS（最新版）
- Linux（主要ディストリビューション）

**必要要件：**
- ターミナルエミュレータ（TTY接続が必須）

**推奨ターミナル：**
- Windows Terminal
- iTerm2（macOS）
- Kitty
- Alacritty
- VSCode内蔵ターミナル

---

## 2. 起動・終了手順

### 2.1 Nushellの起動方法

1. ターミナルエミュレータを開きます
2. 以下のコマンドを入力してNushellを起動します

```
nu
```

3. プロンプトが表示されれば起動完了です

```
~>
```

**起動オプション：**

| オプション | 説明 |
|----------|------|
| `nu` | 通常起動（REPLモード） |
| `nu script.nu` | スクリプトファイルを実行 |
| `nu -c "command"` | 指定したコマンドを実行して終了 |
| `nu --lsp` | LSPサーバーモードで起動（エディタ連携用） |

### 2.2 終了方法

以下のいずれかの方法でNushellを終了できます：

**方法1: exitコマンド**
```
exit
```

**方法2: Ctrl+D**
- キーボードで「Ctrl」キーを押しながら「D」キーを押します

### 2.3 設定ファイルの場所

初回起動時にデフォルト設定ファイルが生成されます。設定ファイルの場所は以下のコマンドで確認できます：

```
$nu.config-path
```

---

## 3. メインREPL画面

### 3.1 画面構成

メインREPL画面は以下の要素で構成されています：

| 要素 | 説明 |
|------|------|
| 左プロンプト | カレントディレクトリ等を表示 |
| 右プロンプト | 時刻、Gitブランチ名等を表示（カスタマイズ可能） |
| 入力行 | コマンドを入力する行（シンタックスハイライト付き） |
| ヒント | 履歴ベースの入力補完候補（薄い色で表示） |
| 実行結果 | コマンドの出力（テーブル/テキスト形式） |

### 3.2 基本操作

| 操作 | キー | 説明 |
|------|-----|------|
| コマンド実行 | Enter | 入力したコマンドを実行 |
| 補完 | Tab | コマンド名、パス等の補完候補を表示 |
| 履歴検索 | Ctrl+R | 過去のコマンド履歴を検索 |
| 行頭へ移動 | Ctrl+A | カーソルを行頭へ移動 |
| 行末へ移動 | Ctrl+E | カーソルを行末へ移動 |
| 入力クリア | Ctrl+U | 現在の入力をクリア |
| 実行中断 | Ctrl+C | 実行中のコマンドを中断 |
| 終了 | Ctrl+D | Nushellを終了 |

### 3.3 Auto-cd機能

ディレクトリパスを直接入力するだけで、そのディレクトリに移動できます。

**例：**
```
# 以下のように入力するだけでディレクトリ移動
../projects
```

これは `cd ../projects` と同等です。

---

## 4. 【STEP1】コマンド入力・実行

> **業務フローでの位置**: ユーザーがコマンドを入力し、Nushellが構文解析・実行を行うステップです。

### 4.1 コマンドの基本構文

```
コマンド名 引数1 引数2 --フラグ 値
```

**例：**
```
# ファイル一覧を表示
ls

# 特定のディレクトリを表示
ls /path/to/directory

# ロングフォーマットで表示
ls -l

# ファイル名でフィルタ
ls | where name =~ "*.txt"
```

### 4.2 パイプライン処理

Nushellの特徴は、パイプライン（`|`）を使って複数のコマンドを連結し、データを順次処理できることです。

**例：**
```
# ファイル一覧からサイズでソート
ls | sort-by size

# 特定の拡張子のファイルのみ表示
ls | where name ends-with ".txt"

# ファイルサイズの合計を計算
ls | get size | math sum
```

### 4.3 構造化データの表示

コマンドの実行結果はテーブル形式で表示されます：

```
~> ls
+----+--------------------+------+----------+------------+
| #  | name               | type | size     | modified   |
+----+--------------------+------+----------+------------+
| 0  | README.md          | file | 2.5 KB   | 2 days ago |
| 1  | Cargo.toml         | file | 1.2 KB   | 1 week ago |
| 2  | src                | dir  | 4.0 KB   | 3 days ago |
+----+--------------------+------+----------+------------+
```

### 4.4 変数の使用

変数を使ってデータを保存・再利用できます：

```
# 変数に値を代入
let files = (ls)

# 変数を使用
$files | where size > 1KB

# 可変変数
mut counter = 0
$counter = $counter + 1
```

---

## 5. 【STEP2-3】補完機能の活用

> **業務フローでの位置**: コマンド入力中に補完機能を活用して、効率的に入力を行うステップです。

### 5.1 基本的な補完操作

**Tabキーで補完候補を表示：**

1. コマンド名の一部を入力します
2. 「Tab」キーを押します
3. 補完候補がメニュー形式で表示されます
4. 上下キーで候補を選択し、Enter/Tabで確定します

### 5.2 補完の種類

| 補完種別 | 説明 | 例 |
|---------|------|-----|
| コマンド補完 | コマンド名を補完 | `ls`, `cd`, `where` |
| ファイル補完 | ファイルパスを補完 | `/path/to/file` |
| ディレクトリ補完 | ディレクトリパスを補完 | `/path/to/dir/` |
| 変数補完 | 変数名を補完 | `$env`, `$nu` |
| フラグ補完 | コマンドのフラグを補完 | `--help`, `-l` |
| カスタム補完 | コマンド固有の補完 | `git checkout <branch>` |

### 5.3 ヘルプ補完メニュー

F1キー（または設定されたキー）を押すと、ヘルプ情報を含む補完メニューが表示されます。

**表示される情報：**
- コマンド名
- コマンドの説明
- 使用法（Usage）
- フラグ一覧
- パラメータ一覧
- 使用例

### 5.4 補完設定のカスタマイズ

設定ファイル（`config.nu`）で補完の動作をカスタマイズできます：

```
# 大文字小文字の区別
$env.config.completions.case_sensitive = false

# マッチアルゴリズム（prefix/fuzzy）
$env.config.completions.algorithm = "fuzzy"

# ソート順
$env.config.completions.sort = "smart"
```

---

## 6. 【STEP3-4】データ探索（Explore）

> **業務フローでの位置**: コマンド実行結果をインタラクティブに探索・確認するステップです。

### 6.1 Exploreの起動

`explore`コマンドを使用してデータを探索モードで表示します：

```
# ファイル一覧を探索
ls | explore

# 環境変数を探索
$env | explore

# JSONファイルを探索
open data.json | explore
```

### 6.2 レコードビューの操作

テーブルやレコードデータを表示する画面です。

**操作方法：**

| 操作 | キー | 説明 |
|------|-----|------|
| スクロール | 矢印キー | 表示位置を移動 |
| ページ移動 | Page Up/Down | ページ単位で移動 |
| カーソルモード | Enter | セル選択モードに切り替え |
| ドリルダウン | Enter（カーソルモード時） | ネストしたデータに入る |
| 転置 | t | 行と列を入れ替え |
| 展開 | e | 選択したデータを展開表示 |
| 戻る | Esc | 前の画面に戻る |
| 終了 | :q | Exploreを終了 |

**モードの切り替え：**

- **VIEWモード**: 画面全体をスクロールして閲覧
- **CURSORモード**: 個々のセルを選択して操作

### 6.3 バイナリビュー

バイナリデータを表示する画面です。16進数表示とASCII表示を並べて表示します。

```
open binary_file.bin | explore
```

### 6.4 Exploreコマンド

Explore内で使用できるコマンド（コロン`:`で開始）：

| コマンド | 説明 |
|---------|------|
| `:help` | ヘルプを表示 |
| `:try` | Tryビューでコマンドを試す |
| `:nu <cmd>` | Nuコマンドを実行 |
| `:q` | Exploreを終了 |

---

## 7. 【STEP4-5】スクリプト作成・実行

> **業務フローでの位置**: 繰り返し行う処理をスクリプトとして作成・実行するステップです。

### 7.1 スクリプトファイルの作成

Nushellスクリプトは`.nu`拡張子のファイルとして作成します：

```nu
# script.nu

# 変数定義
let target_dir = "/path/to/directory"

# 処理
ls $target_dir | where size > 1MB | each { |file|
    print $"Large file: ($file.name)"
}
```

### 7.2 スクリプトの実行

```
# スクリプトを実行
nu script.nu

# または source で読み込み
source script.nu
```

### 7.3 カスタムコマンドの定義

```nu
# カスタムコマンドの定義
def greet [name: string] {
    print $"Hello, ($name)!"
}

# 使用
greet "World"
```

### 7.4 LSP連携（エディタ統合）

VSCodeなどのエディタでNushellスクリプトを開発する際、LSPサーバーを使用することで以下の機能が利用できます：

- コード補完
- 定義ジャンプ
- ホバー情報表示
- 構文エラーの即時表示
- シンボル検索
- リネーム

**LSPサーバーの起動：**
```
nu --lsp
```

通常はエディタ拡張機能が自動的にLSPサーバーを起動します。

---

## 8. ヘルプ機能

### 8.1 helpコマンドの基本

```
# 総合ヘルプを表示
help

# 特定のコマンドのヘルプを表示
help ls

# コマンドを検索
help --find "file"
```

### 8.2 ヘルプサブコマンド

| コマンド | 説明 |
|---------|------|
| `help commands` | コマンド一覧を表示 |
| `help aliases` | エイリアス一覧を表示 |
| `help modules` | モジュール一覧を表示 |
| `help operators` | 演算子一覧を表示 |
| `help externs` | extern宣言一覧を表示 |
| `help escapes` | エスケープシーケンス一覧を表示 |

### 8.3 --helpフラグ

各コマンドには`--help`フラグが利用できます：

```
ls --help
```

---

## 9. 履歴機能

### 9.1 履歴の検索

```
# Ctrl+R で履歴を検索
# インクリメンタルに履歴を絞り込み

# 履歴コマンドで一覧表示
history
```

### 9.2 履歴の管理

```
# 履歴を検索
history | where command =~ "ls"

# 履歴から実行
history | get 5 | run
```

### 9.3 履歴の設定

設定ファイルで履歴の動作をカスタマイズできます：

```
# 履歴のファイルフォーマット（sqlite/plaintext）
$env.config.history.file_format = "sqlite"

# 履歴の最大件数
$env.config.history.max_size = 10000

# 履歴の同期
$env.config.history.sync_on_enter = true
```

**注意**: スペースで始まるコマンドは履歴に保存されません（機密情報保護）。

---

## 10. 設定カスタマイズ

### 10.1 設定ファイルの場所

```
# 設定ファイルのパスを確認
$nu.config-path

# 環境設定ファイルのパスを確認
$nu.env-path
```

### 10.2 主な設定項目

**config.nu の主要設定：**

```nu
# シェルの動作設定
$env.config = {
    # カーソル形状
    cursor_shape: {
        emacs: line
        vi_insert: line
        vi_normal: block
    }

    # 補完設定
    completions: {
        case_sensitive: false
        algorithm: "fuzzy"
    }

    # テーブル表示設定
    table: {
        mode: rounded
        index_mode: always
    }

    # 履歴設定
    history: {
        max_size: 10000
        file_format: "sqlite"
    }
}
```

### 10.3 プロンプトのカスタマイズ

**env.nu でプロンプトを設定：**

```nu
# 左プロンプト
$env.PROMPT_COMMAND = {||
    let dir = ($env.PWD | path basename)
    $"($dir)> "
}

# 右プロンプト
$env.PROMPT_COMMAND_RIGHT = {||
    (date now | format date "%H:%M:%S")
}
```

---

## 11. 日常業務の流れ

本セクションでは、業務フローに沿った日常業務の流れを説明します。

```
業務フロー概要（再掲）
+---------------------------------------------------------------------+
【STEP 1】コマンドの入力 → 4章参照
    ↓
【STEP 2】入力支援機能の活用 → 5章参照
    ↓
【STEP 3】コマンドの実行 → 4章参照
    ↓
【STEP 4】結果の確認・探索 → 6章参照
    ↓
【STEP 5】次の操作へ → 7章参照
+---------------------------------------------------------------------+
```

### 11.1 【ユーザー】STEP1-2: コマンド入力と補完活用

1. Nushellを起動します
2. 実行したいコマンドの先頭を入力します
3. Tabキーを押して補完候補を表示します
4. 矢印キーで候補を選択し、Enter/Tabで確定します
5. 必要なオプションやパスを入力します

**ポイント：**
- 長いコマンド名やパスは補完を活用
- F1キーでコマンドのヘルプを確認
- シンタックスハイライトで構文エラーを事前に発見

### 11.2 【ユーザー】STEP3: コマンド実行

1. コマンド入力が完了したらEnterキーを押します
2. コマンドが実行され、結果が表示されます
3. エラーが発生した場合は、エラーメッセージを確認します

**ポイント：**
- 実行中のコマンドはCtrl+Cで中断可能
- Auto-cd機能でディレクトリ移動が簡単

### 11.3 【ユーザー】STEP4: 結果の確認と探索

1. 出力結果を確認します
2. 大量のデータの場合は `| explore` でインタラクティブに探索します
3. 必要に応じてフィルタリングやソートを追加します

```
# 例: 大きなJSONファイルを探索
open large-data.json | explore
```

### 11.4 【ユーザー】STEP5: 次の操作へ

1. 結果を確認して次の処理を決定します
2. パイプラインで追加の処理をつなげます
3. 結果をファイルに保存します

```
# 例: フィルタリング結果をファイルに保存
ls | where size > 1MB | save large-files.json
```

---

## 12. よくある質問と対処法

### 12.1 起動に関するQ&A

**Q: Nushellが起動しません**

A: 以下を確認してください：
- ターミナルがTTYに接続されていることを確認
- Nushellが正しくインストールされているか確認（`which nu`）
- パスが正しく設定されているか確認

**Q: 設定ファイルが見つかりません**

A: 以下のコマンドで場所を確認してください：
```
$nu.config-path
```

### 12.2 コマンド実行に関するQ&A

**Q: コマンドが見つかりません**

A: 以下を確認してください：
- コマンド名のスペルを確認
- `help commands` で利用可能なコマンドを確認
- 外部コマンドの場合はパスが通っているか確認

**Q: 補完が効きません**

A: 以下を確認してください：
- Tab キーを押しているか確認
- 設定ファイルの補完設定を確認
- 外部コマンドの場合は外部補完が有効か確認

### 12.3 データ処理に関するQ&A

**Q: テーブルの列が切れて表示されます**

A: 以下の方法を試してください：
- ターミナルウィンドウを広げる
- `| explore` でインタラクティブに閲覧
- `| table -e` で展開表示

**Q: 大きなファイルの処理が遅いです**

A: 以下を確認してください：
- 必要な部分だけフィルタリング
- `first N` で先頭N行だけ処理
- ストリーミング処理を活用

---

## 13. トラブルシューティング

### 13.1 エラーメッセージと対処法

| エラーメッセージ | 原因 | 対処法 |
|----------------|------|--------|
| Nushell launched as a REPL, but STDIN is not a TTY | 標準入力がTTYでない | ターミナルエミュレータから直接起動 |
| Parse error | 構文エラー | エラー表示のスパン情報を確認し、構文を修正 |
| Command not found | コマンドが存在しない | コマンド名を確認、または外部コマンドのパスを確認 |
| Variable not found | 変数が未定義 | 変数が正しく定義されているか確認 |
| Permission denied | 権限不足 | ファイル・ディレクトリの権限を確認 |
| Cannot change directory | ディレクトリ移動失敗 | パスが存在するか、アクセス権があるか確認 |

### 13.2 よくあるトラブルと解決方法

**トラブル: REPLがフリーズした**

解決方法：
1. Ctrl+C を押して現在の処理を中断
2. それでも反応しない場合は、別のターミナルから `kill` コマンドで終了
3. 再起動後、問題のコマンドを確認

**トラブル: 設定変更が反映されない**

解決方法：
1. 設定ファイルの構文エラーがないか確認
2. Nushellを再起動
3. `source $nu.config-path` で設定を再読み込み

**トラブル: 履歴が保存されない**

解決方法：
1. 履歴ファイルのパーミッションを確認
2. `$env.config.history` の設定を確認
3. SQLite形式の場合、データベースファイルの状態を確認

### 13.3 サポートへの連絡方法

**公式リソース：**
- GitHub Issues: https://github.com/nushell/nushell/issues
- Discord: Nushell公式Discord
- ドキュメント: https://www.nushell.sh/

**情報提供時の推奨事項：**
- Nushellのバージョン（`version`コマンドで確認）
- OS情報
- 問題の再現手順
- エラーメッセージの全文

---

## 改訂履歴

| 版数 | 改訂日 | 改訂内容 |
|-----|--------|---------|
| 1.0 | 2026-03-01 | 初版作成 |

---

*本マニュアルは、Nushellのエンドユーザー向け業務運用マニュアルです。*
*システムの更新により、画面や操作方法が変更される場合があります。*
