The CLI
The darkpyonix CLI
Every command takes the notebook file, not a kernel id. The CLI finds or starts a manager, and the manager finds or starts the file's kernel.
Commands
| Command | What it does |
|---|---|
darkpyonix run FILE [--cells 1,3] [--param k=v]… [--python PATH] [--queue] [--detach] | Runs the file or the listed cells and follows the output. The exit code follows the run: 0 ok, 1 error, 130 interrupted. Ctrl-C interrupts the run; a second Ctrl-C detaches and the run continues. |
darkpyonix stop FILE | Interrupts the running cell. The namespace and the process stay. |
darkpyonix status [FILE], darkpyonix ps | Status of one kernel, or the list of running kernels. |
darkpyonix logs FILE [--run latest|ID] [--follow] | Prints a run log. --follow replays the running run and keeps following it. |
darkpyonix attach FILE | Follows the kernel's live events. |
darkpyonix vars FILE | Lists user variables with name, type and a short summary. While a cell runs, only name and type are shown, so no user __repr__ runs. |
darkpyonix restart FILE [--hard] | Soft restart clears the namespace. --hard re-executes the process with the same interpreter; the kernel id stays. |
darkpyonix shutdown FILE [--force] | Interrupts, finishes the run log and exits cleanly. Only --force kills the process. |
darkpyonix kernel FILE [--python PATH] | Starts the kernel without running anything. |
darkpyonix share FILE --permission viewer1|viewer2|viewer3 | Issues a share token for the file's kernel. Needs a dedicated manager. Becomes --capabilities read,history,... changing #49 |
darkpyonix manager [--ephemeral|--dedicated] [--host H] [--port P] [--idle-timeout S] | Runs a manager. The default is ephemeral: loopback only, exits when idle. Giving both modes is an error. |
--cells takes indexes and ranges (1,3, 2-4); the preamble is
0. --param name=value parses the value as JSON, otherwise it is a string.
--json prints machine-readable output.
Exit codes
| Code | Meaning |
|---|---|
0 | The run finished ok. |
1 | A cell raised. The traceback is printed, without kernel frames. |
130 | The run was interrupted. |
75 | The file's kernel is already running something. Nothing was started. |
When the file is busy
A second run of the same file is refused by default and prints the current run's id,
start time and cells, plus a hint. Add --queue to wait in line instead. Queued runs start
in arrival order.
Stop, restart, shut down
stop raises KeyboardInterrupt in the running cell, typically within a second.
The run ends as interrupted, the queue stays, and every variable is still there for the
next run. No DarkPyonix command kills a kernel to stop a run.
restart clears the namespace. restart --hard re-executes the process with the
same interpreter and arguments; the kernel id stays. shutdown interrupts, finishes writing
the run log and exits. Only shutdown --force kills the process.
For agents
The CLI replaces the shell habits that lose work:
| Before | With DarkPyonix |
|---|---|
python train.py > log.txt & | darkpyonix run train.py --detach (the log is written for you) |
pkill -f train.py | darkpyonix stop train.py (interrupt, state kept) |
tail -f log.txt | darkpyonix logs train.py --follow |
| running the same file again by mistake | exit code 75 with the current run |
| forgetting what was computed | darkpyonix vars train.py, or __runs__ in the kernel |
Which manager
Today the CLI picks a live manager from ~/.darkpyonix/managers/*.json and starts an
ephemeral one when there is none. An agent does not need to know another manager's token; the same OS
user is enough. The ephemeral manager exits after 120 idle seconds by default; the kernels stay.
Registry files are being removed changing #50. The CLI will use DARKPYONIX_MANAGER_URL and DARKPYONIX_TOKEN when they are set, and otherwise start its own ephemeral manager and read its address and token from that process. The commands and their behavior above do not change.