Metadata-Version: 2.4
Name: pykernel-cli
Version: 1.4.0
Summary: A hackable Python REPL with first-class command support
Author-email: zKaiden <odrekzinho@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/odrekzinho-art/pykernel
Project-URL: Repository, https://github.com/odrekzinho-art/pykernel
Project-URL: Bug Tracker, https://github.com/odrekzinho-art/pykernel/issues
Keywords: repl,shell,interactive,python
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Interpreters
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# PyKernel

[![PyPI version](https://img.shields.io/pypi/v/pykernel-cli)](https://pypi.org/project/pykernel-cli/)
[![Python](https://img.shields.io/pypi/pyversions/pykernel-cli)](https://pypi.org/project/pykernel-cli/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://img.shields.io/pypi/dm/pykernel-cli)](https://pypistats.org/packages/pykernel-cli)

A hackable Python REPL with first-class command support.

## Install

```bash
pip install pykernel-cli
```

## Usage

```bash
pykernel
# or
python -m pykernel
```

Type `/help` to see all commands.

### Flags

| Flag      | Description                  |
| --------- | ---------------------------- |
| `--ver`   | Show the current version     |
| `--dev`   | Show plugin dev reference    |

## Commands

### Core
| Command             | Aliases         | Description                        |
| ------------------- | --------------- | ---------------------------------- |
| `/help [command]`   | `/?` `/commands`| List commands or describe one      |
| `/exit`             | `/quit` `/q`    | Exit the kernel                    |
| `/clear`            | `/cls`          | Clear the terminal screen          |
| `/history [n]`      | `/hist`         | Show last n inputs (default 20)    |
| `/run <file.py>`    |                 | Execute a Python file              |
| `/reset`            |                 | Clear the execution namespace      |
| `/alias <new> <target>` |             | Create an alias for a command      |

### Inspector
| Command          | Aliases       | Description                          |
| ---------------- | ------------- | ------------------------------------ |
| `/vars`          | `/ls` `/env`  | List variables in the namespace      |
| `/who <name>`    |               | Show detailed info about a variable  |
| `/doc <name>`    |               | Show a variable's docstring          |
| `/source <name>` | `/src`        | Show source code of a function/class |
| `/del <name>`    | `/rm`         | Delete a variable                    |
| `/timeit <expr>` |               | Time an expression                   |

### Shell
| Command       | Aliases | Description                              |
| ------------- | ------- | ---------------------------------------- |
| `/sh <cmd>`   | `/!`    | Run a shell command (output stored in `_out`) |
| `/cd <path>`  |         | Change working directory                 |
| `/pwd`        |         | Print working directory                  |
| `/ls [path]`  |         | List directory contents                  |

### Snippets
| Command             | Description                          |
| ------------------- | ------------------------------------ |
| `/snip save <name>` | Save last history entry as a snippet |
| `/snip write <name>`| Create a snippet in `$EDITOR`        |
| `/snip list`        | List all saved snippets              |
| `/snip show <name>` | Print a snippet's source             |
| `/snip run <name>`  | Execute a snippet                    |
| `/snip edit <name>` | Edit a snippet in `$EDITOR`          |
| `/snip del <name>`  | Delete a snippet                     |

## Plugins

Drop a `.py` file with a `register(registry)` function into `~/.pykernel/plugins/`:

```python
def register(reg):
    @reg.command("hello", help="Say hello")
    def cmd_hello(ctx, *args):
        ctx.print("Hello!")
```

Plugins load automatically on startup. Run `pykernel --dev` for the full plugin dev reference.

## Config

Edit `~/.pykernel/config.toml`:

```toml
[kernel]
prompt = ">>> "
theme  = "dark"   # dark | light | none
```

## Troubleshooting

**`pykernel` command not found on Windows?**

Run with `python -m pykernel` instead, or add Python's `Scripts` folder to your PATH:
`C:\Users\<you>\AppData\Local\Programs\Python\Python3xx\Scripts\`

## License

[MIT](./LICENSE)
