0
# Command-Line Tools
1

2
Command-line utilities for Jupyter ecosystem management including the main jupyter command dispatcher, IPython-to-Jupyter migration tools, and system troubleshooting utilities. These tools provide essential functionality for system administration and user support.
3

4
## Capabilities
5

6
### Main Jupyter Command
7

8
The primary `jupyter` command that serves as a dispatcher to subcommands and provides system information.
9

10
```python { .api }
11
def main() -> None:
12
    """The command entry point for the 'jupyter' command.
13
    
14
    Handles subcommand dispatching, path information display,
15
    version information, and help functionality.
16
    """
17

18
def jupyter_parser() -> JupyterParser:
19
    """Create a jupyter argument parser.
20
    
21
    Returns:
22
        JupyterParser: Configured argument parser for jupyter command
23
    """
24

25
def list_subcommands() -> list[str]:
26
    """List all jupyter subcommands.
27
    
28
    Searches PATH for `jupyter-name` executables and returns 
29
    subcommand names without the `jupyter-` prefix.
30
    
31
    Returns:
32
        list[str]: Available subcommand names
33
    """
34
```
35

36
**Usage Example:**
37

38
```python
39
from jupyter_core.command import list_subcommands, main
40

41
# List available subcommands
42
subcommands = list_subcommands()
43
print("Available subcommands:", subcommands)
44

45
# The main() function is typically called from command line:
46
# $ jupyter --version
47
# $ jupyter --paths
48
# $ jupyter notebook
49
```
50

51
The `jupyter` command supports several built-in options:
52

53
- `--version`: Show versions of core Jupyter packages
54
- `--paths`: Show all Jupyter paths (config, data, runtime)
55
- `--config-dir`: Show Jupyter config directory
56
- `--data-dir`: Show Jupyter data directory  
57
- `--runtime-dir`: Show Jupyter runtime directory
58
- `--json`: Output paths as JSON (with --paths)
59
- `--debug`: Show debug information about path resolution (with --paths)
60

61
### Jupyter Parser Class
62

63
Custom argument parser for the jupyter command with auto-completion support.
64

65
```python { .api }
66
class JupyterParser(argparse.ArgumentParser):
67
    """A Jupyter argument parser with auto-completion support."""
68
    
69
    @property
70
    def epilog(self) -> str:
71
        """Add subcommands to epilog on request.
72
        
73
        Avoids searching PATH for subcommands unless help output is requested.
74
        """
75
    
76
    def argcomplete(self) -> None:
77
        """Trigger auto-completion, if enabled.
78
        
79
        Uses argcomplete library if available for bash/zsh completion.
80
        """
81
```
82

83
### Migration Tools
84

85
Tools for migrating IPython < 4.0 configurations and data to Jupyter locations.
86

87
```python { .api }
88
def migrate() -> bool:
89
    """Migrate IPython configuration to Jupyter.
90
    
91
    Copies (doesn't move) IPython configuration files, kernels,
92
    extensions, and other data to appropriate Jupyter locations.
93
    
94
    Returns:
95
        bool: True if any files were migrated
96
    """
97

98
def migrate_dir(src: str, dst: str) -> bool:
99
    """Migrate a directory from src to dst.
100
    
101
    Args:
102
        src: Source directory path
103
        dst: Destination directory path
104
        
105
    Returns:
106
        bool: True if directory was migrated
107
    """
108

109
def migrate_file(src: str | Path, dst: str | Path, substitutions=None) -> bool:
110
    """Migrate a single file from src to dst.
111
    
112
    Args:
113
        src: Source file path
114
        dst: Destination file path  
115
        substitutions: Optional dict of {regex: replacement} for text substitution
116
        
117
    Returns:
118
        bool: True if file was migrated
119
    """
120

121
def migrate_one(src: str, dst: str) -> bool:
122
    """Migrate one item from src to dst.
123
    
124
    Generic migration dispatcher that handles both files and directories.
125
    
126
    Args:
127
        src: Source path (file or directory)
128
        dst: Destination path
129
        
130
    Returns:
131
        bool: True if item was migrated
132
    """
133

134
def migrate_static_custom(src: str, dst: str) -> bool:
135
    """Migrate non-empty custom.js,css from src to dst.
136
    
137
    Handles migration of custom CSS and JavaScript files from
138
    IPython profile directories to Jupyter custom directories.
139
    
140
    Args:
141
        src: Source directory path
142
        dst: Destination directory path
143
        
144
    Returns:
145
        bool: True if custom files were migrated
146
    """
147

148
def migrate_config(name: str, env: Any) -> list[Any]:
149
    """Migrate a config file with text substitutions.
150
    
151
    Applies regex substitutions to update IPython class names
152
    and configuration patterns to Jupyter equivalents.
153
    
154
    Args:
155
        name: Configuration file name
156
        env: Configuration environment/context
157
        
158
    Returns:
159
        list[Any]: List of migrated configuration objects
160
    """
161

162
def get_ipython_dir() -> str:
163
    """Return the IPython directory location.
164
    
165
    Checks IPYTHONDIR environment variable, defaults to ~/.ipython.
166
    
167
    Returns:
168
        str: Path to IPython directory
169
    """
170
```
171

172
**Usage Example:**
173

174
```python
175
from jupyter_core.migrate import migrate, get_ipython_dir
176

177
# Check if IPython directory exists
178
ipython_dir = get_ipython_dir()
179
print(f"IPython directory: {ipython_dir}")
180

181
# Perform migration
182
if migrate():
183
    print("Successfully migrated IPython configuration to Jupyter")
184
else:
185
    print("No migration needed")
186
```
187

188
The migration process handles:
189

190
- **Configuration files**: `ipython_notebook_config.py` → `jupyter_notebook_config.py`  
191
- **Kernels**: `~/.ipython/kernels/` → `{jupyter_data_dir}/kernels/`
192
- **Extensions**: `~/.ipython/extensions/` → `{jupyter_data_dir}/nbextensions/`
193
- **Custom files**: `~/.ipython/profile_default/static/custom/` → `~/.jupyter/custom/`
194
- **Security files**: Notebook secrets and signatures
195
- **Text substitutions**: Updates class names (IPythonApp → JupyterApp, etc.)
196

197
### Migration Application Class
198

199
Command-line application for running migrations.
200

201
```python { .api }
202
class JupyterMigrate(JupyterApp):
203
    """A Jupyter Migration App.
204
    
205
    Command-line application that migrates IPython < 4.0 configuration
206
    and data to Jupyter locations.
207
    """
208
    
209
    name: str = "jupyter-migrate"
210
    description: str  # Multi-line description of migration process
211
    
212
    def start(self) -> None:
213
        """Start the migration process."""
214
```
215

216
### Troubleshooting Tools
217

218
System information gathering tools for diagnosing Jupyter installation issues.
219

220
```python { .api }
221
def get_data() -> dict[str, Any]:
222
    """Returns a dict of various user environment data.
223
    
224
    Gathers comprehensive system information including:
225
    - PATH and sys.path
226
    - Python executable and version
227
    - Platform information  
228
    - Jupyter command locations
229
    - Package lists (pip, conda)
230
    - Environment exports
231
    
232
    Returns:
233
        dict[str, Any]: Environment data dictionary
234
    """
235

236
def subs(cmd: list[str] | str) -> str | None:
237
    """Get data from commands that need to run outside of Python.
238
    
239
    Args:
240
        cmd: Command to execute (string or list)
241
        
242
    Returns:
243
        str | None: Command output or None if command failed
244
    """
245

246
def main() -> None:
247
    """Print out comprehensive system information for troubleshooting."""
248
```
249

250
**Usage Example:**
251

252
```python
253
from jupyter_core.troubleshoot import get_data, main
254

255
# Get structured environment data
256
env_data = get_data()
257
print("Python executable:", env_data['sys_exe'])
258
print("Platform:", env_data['platform'])
259
print("Jupyter locations:", env_data.get('which'))
260

261
# Or run the full troubleshooting report
262
main()  # Prints comprehensive system information
263
```
264

265
The troubleshooting output includes:
266

267
- **$PATH**: All directories in system PATH
268
- **sys.path**: Python module search paths  
269
- **sys.executable**: Python interpreter location
270
- **sys.version**: Python version information
271
- **platform.platform()**: System platform details
272
- **which/where jupyter**: Jupyter command locations
273
- **pip list**: Installed Python packages
274
- **conda list**: Conda package information (if available)
275
- **conda env export**: Full conda environment (if available)
276

277
### Command Execution Utilities
278

279
Internal utilities for cross-platform command execution and subcommand discovery.
280

281
```python { .api }
282
def _jupyter_abspath(subcommand: str) -> str:
283
    """Get the absolute path of a specified jupyter subcommand.
284
    
285
    Args:
286
        subcommand: Name of subcommand (without 'jupyter-' prefix)
287
        
288
    Returns:
289
        str: Absolute path to subcommand executable
290
        
291
    Raises:
292
        Exception: If subcommand not found or not executable
293
    """
294

295
def _path_with_self() -> list[str]:
296
    """Put jupyter's directory at the front of PATH.
297
    
298
    Ensures that /path/to/jupyter subcommand will find 
299
    /path/to/jupyter-subcommand even if other versions 
300
    are ahead on PATH.
301
    
302
    Returns:
303
        list[str]: Modified PATH directories
304
    """
305

306
def _execvp(cmd: str, argv: list[str]) -> None:
307
    """Cross-platform execvp that handles Windows properly.
308
    
309
    Python's execvp has problematic behavior on Windows,
310
    so this uses Popen on Windows and execvp on Unix.
311
    
312
    Args:
313
        cmd: Command to execute
314
        argv: Command arguments
315
    """
316
```
317

318
## Command-Line Entry Points
319

320
Based on the package configuration, these commands are available after installation:
321

322
### jupyter
323
Main command dispatcher (`jupyter_core.command:main`)
324

325
```bash
326
# Show version information
327
jupyter --version
328

329
# Show all Jupyter paths
330
jupyter --paths
331

332
# Show specific directories  
333
jupyter --config-dir
334
jupyter --data-dir
335
jupyter --runtime-dir
336

337
# Show paths as JSON
338
jupyter --paths --json
339

340
# Debug path resolution
341
jupyter --paths --debug
342

343
# Run subcommands
344
jupyter notebook
345
jupyter lab
346
jupyter console
347
```
348

349
### jupyter-migrate  
350
IPython migration tool (`jupyter_core.migrate:main`)
351

352
```bash
353
# Migrate IPython configuration to Jupyter
354
jupyter-migrate
355

356
# The command is idempotent - safe to run multiple times
357
# Creates a marker file to avoid duplicate migrations
358
```
359

360
### jupyter-troubleshoot
361
System troubleshooting tool (`jupyter_core.troubleshoot:main`)
362

363
```bash  
364
# Display comprehensive system information
365
jupyter-troubleshoot
366

367
# Output includes PATH, Python info, package lists, etc.
368
# Useful for diagnosing installation and configuration issues
369
```
370

371
## Subcommand Discovery
372

373
The jupyter command automatically discovers subcommands by searching PATH for executables matching the pattern `jupyter-*`. This allows any package to provide Jupyter subcommands by installing appropriately named executables.
374

375
**Subcommand Resolution Order:**
376
1. Check if first argument matches a subcommand name
377
2. Search PATH for `jupyter-{subcommand}` executable  
378
3. Verify executable permissions
379
4. Execute with remaining arguments
380

381
**Example Subcommands:**
382
- `jupyter-notebook` → `jupyter notebook`
383
- `jupyter-lab` → `jupyter lab`  
384
- `jupyter-console` → `jupyter console`
385
- `jupyter-kernelspec` → `jupyter kernelspec`
386

387
This design enables a distributed ecosystem where different packages can contribute functionality to the unified `jupyter` command interface.