jz-cli

A command-line interface (CLI) helper for the Jean Zay SLURM cluster at IDRIS.

This typer-based CLI simplifies common tasks such as syncing files, managing SSH connections, and interacting with the SLURM scheduler and IDRIS-specific commands.

Features

• File Synchronization: Sync your local project directory with the Jean Zay cluster using rsync.
• Persistent SSH Connections: Maintain a persistent SSH connection for faster access and command execution.
• HTTP Proxies Over SSH: Expose local HTTP endpoints that relay requests to services running on Jean Zay compute nodes.
• SCRATCH Timestamp Renewal: Refresh timestamps under your remote $SCRATCH.
• SLURM Job Management: View your job queue and cancel jobs.
• IDRIS Resource Management: Check your resource allocations, project status, and disk quotas.

Installation

1. Install the dependencies:

   Install with uv (recommended; installs it in an isolated environment).

   uv tool install --python 3.12 git+https://github.com/alex-bene/jz-cli/

   or with pip

   pip install git+https://github.com/alex-bene/jz-cli/

2. Run the setup:

   jz setup

   This will prompt you for your Jean Zay username and account id. SSH commands use the configured remote_user as the SSH target, and sync commands use it for rsync destinations.

Usage

The jz CLI has several subcommands, each with its own set of options.

jz sync

Sync a local directory to the Jean Zay cluster.

# Sync the current directory
jz sync

# Sync a specific directory
jz sync /path/to/your/project

# Exclude certain files or directories
jz sync -e ".env" -e "data/"

# See more options
jz sync --help

jz ssh

Manage the persistent SSH connection.

# Start the master connection
jz ssh start

# Check the status of the connection
jz ssh status

# Run a command on the remote server
jz ssh run "ls -l"

# Stop the master connection
jz ssh stop

jz proxy

Expose a local HTTP endpoint that relays requests over ordinary SSH to a service running on a Jean Zay compute node.

# Expose a generic HTTP service running on the compute node
jz proxy serve --job-id 123456 --remote-port 8080 --local-port 8000

# Restrict the proxy to a subset of paths
jz proxy serve --node jzxh033 --remote-port 8080 --allow-prefix /api/

# Target a remote host other than localhost on the compute node
jz proxy serve --node jzxh033 --remote-host 10.0.0.12 --remote-port 8080

# Allow only GET and POST through the generic proxy
jz proxy serve --node jzxh033 --remote-port 8080 --allow-method GET --allow-method POST

# Use the OpenAI-specific wrapper for vLLM or another OpenAI-compatible server
jz proxy openai --job-name vllm-serve --remote-port 8888 --local-port 8000

Notes:

• jz proxy serve is a generic HTTP proxy. It is not a raw TCP tunnel.
• Use exactly one of --node, --job-id, or --job-name.
• --allow-method is repeatable. If omitted, all methods are allowed.
• --allow-prefix is repeatable. If omitted, all paths are allowed.
• jz proxy openai targets localhost on the compute node, allows only GET and POST, only forwards /v1/ and /health, and rejects requests with "stream": true.
• Every proxy also exposes a local health check at /_jz/health.
• This avoids SSH port forwarding, which Jean Zay disables.
• --job-id is safer than --job-name if multiple similarly named jobs may be running.

jz scratch

Refresh timestamps under your remote $SCRATCH.

# Run one immediate renewal
jz scratch renew

jz scratch renew connects over SSH, verifies that $SCRATCH is set and points to a remote directory, then runs touch -c on each file and directory below it.

jz slurm

Interact with the SLURM scheduler.

# Show your job queue
jz slurm queue

# Cancel a specific job
jz slurm cancel 12345

# Cancel all your jobs
jz slurm cancel --all

jz idris

Use IDRIS-specific commands.

# Check your resource allocations
jz idris allocations

# View your projects
jz idris projects

# Check your resource consumption
jz idris consumption

# Check your disk quota
jz idris disk-quota

jz config

Manage the CLI configuration.

# Show the current configuration
jz config show

# Show or set your remote_user
jz config remote-user
jz config remote-user --set my-new-username

Development

To contribute to this project, please ensure you have uv installed.

1. Clone the repository:

   git clone https://github.com/alex-bene/jz-cli.git
   cd jz-cli

2. Install dependencies and pre-commit hooks:

   uv sync
   uv run pre-commit install

3. Run checks manually (optional):

   uv run ruff check
   uv run ruff format

This project uses Ruff for linting and formatting. We use pre-commit hooks to ensure code quality.

• Local: Hooks run before every commit (requires pre-commit install).
• GitHub Actions: Runs on every push to auto-fix issues on all branches.
• pre-commit.ci: Runs on every push to check code quality (fixes are handled by the GitHub Action).

License

This project is licensed under the MIT License.