# migs - Google Cloud MIG CLI Tool
A command-line tool that wraps the gcloud CLI to provide an easier experience for managing Google Cloud Managed Instance Groups.
## Features
- List MIGs in your project
- Spin up/down VMs with exact custom names (auto-detects gcloud beta)
- Track your personal VMs
- Automatic SSH config management for VS Code Remote Explorer
- Easy file/directory uploads
- Multi-node cluster support with coordinated naming
## Installation
```bash
pip install migs
```
Or to build from source:
```bash
git clone https://github.com/keatonelvins/migs.git
cd migs
pip install -e .
```
## Prerequisites
- Python 3.8+
- gcloud CLI installed and authenticated (`gcloud auth login`)
- SSH keys configured for Google Compute Engine
- (Optional) gcloud beta component for exact VM naming (`gcloud components install beta`)
## Usage
### List all MIGs
```bash
migs list
```
### Spin up a VM
```bash
# With custom name (auto-detects gcloud beta availability)
migs up my-mig -n my-dev-vm # Creates VM named "my-dev-vm" if beta available
migs up my-mig -n my-dev-vm -d 2h # Auto-delete after 2 hours
migs up my-mig -n node -c 3 # Creates "node1", "node2", "node3"
# Without custom name (auto-generated)
migs up my-mig # Creates "my-mig-username-timestamp"
# Force stable API (bypass auto-detection)
migs up my-mig -n my-dev-vm --stable # Use stable API (VM gets random name, mapped locally)
```
### List your VMs
```bash
migs vms
```
### Sync VM state
```bash
migs sync # Sync local VM list with GCP state
migs sync --discover # Also discover and claim untracked VMs
```
### Check VM connectivity
```bash
migs check my-dev-vm # Test SSH connectivity
```
### SSH into a VM
```bash
migs ssh my-dev-vm
migs ssh my-dev-vm -- tmux attach # Pass additional SSH arguments
```
### Run scripts
```bash
migs run my-dev-vm ./setup.sh # Runs in tmux session
migs run my-dev-vm ./deploy.sh --session deploy # Custom session name
migs run my-dev-vm ./script.sh arg1 arg2 # Pass arguments to script
```
### Environment Variables (.env files)
Both `ssh` and `run` commands automatically detect and use `.env` files from your current directory:
```bash
# If .env exists in current directory, it will be uploaded and sourced
migs ssh my-dev-vm # Variables from .env available in shell
migs run my-dev-vm ./app.sh # Script runs with .env variables
```
The `.env` file is uploaded to `/tmp/.env` on the VM and sourced using `set -a; source /tmp/.env; set +a` to export all variables.
If `$GITHUB_TOKEN` exists in your `.env`, will also configure the gh cli.
### Upload files
```bash
migs upload my-dev-vm ./myfile.txt
migs upload my-dev-vm ./mydir/ /home/user/
```
### Download files
```bash
migs download my-dev-vm /remote/file.txt
migs download my-dev-vm /remote/dir/ ./local/
```
### Spin down a VM
```bash
migs down my-dev-vm
```
### Multi-Node Cluster
```bash
# Create 4-node cluster with coordinated names
migs up my-mig --name cluster -c 4 # Creates cluster1, cluster2, cluster3, cluster4
# SSH to specific nodes
migs ssh cluster1
migs ssh cluster2
# Run script on all nodes
migs run cluster train.py --all
# Shut down entire cluster
migs down cluster --all
```
### Distributed Training (PyTorch)
The `--torchrun` flag automatically sets up environment variables for distributed training:
```bash
# Run distributed training script on all nodes
migs run cluster train.py --all --torchrun
# This automatically sets on each node:
- HEAD_NODE_IP: Internal IP of cluster1 (head node)
- HEAD_NODE_PORT: 5000
- NNODES: Total number of nodes
- NODE_RANK: 0 for head, 1+ for workers
- NPROC_PER_NODE: Auto-detected GPU count
# Your script can then use torchrun:
torchrun --nproc_per_node=$NPROC_PER_NODE \
--nnodes=$NNODES \
--node_rank=$NODE_RANK \
--master_addr=$HEAD_NODE_IP \
--master_port=$HEAD_NODE_PORT \
your_training_script.py
```
## SSH Config
The tool automatically updates your `~/.ssh/config` file with entries for your VMs, making them accessible in VS Code Remote Explorer.
# Release Instructions
### Setup and Installation
```bash
# Install development dependencies and tool in editable mode
make dev-install
# Or directly with pip
pip install -e .
# Install packaging tools (needed for building/releasing)
make install-tools
```
### Building and Testing
```bash
# Build distribution packages
make build
# Clean build artifacts
make clean
```
### Release Process
First increment the `pyproject.toml` and `src/migs/__init__.py`
```bash
# Test upload to PyPI
make test-upload
# Full release (clean, build, upload)
make release
```
Add git version tag:
```bash
git tag v0.1.x
git push origin v0.1.x
```
Raw data
{
"_id": null,
"home_page": null,
"name": "migs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "gcloud, google-cloud, mig, managed-instance-groups, cli",
"author": null,
"author_email": "Keaton Elvins <keatone@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/93/a2/4d9e54c279225fee34276ee6c38e1a9f88b4b391178d4970d42660602cdf/migs-0.1.7.tar.gz",
"platform": null,
"description": "# migs - Google Cloud MIG CLI Tool\n\nA command-line tool that wraps the gcloud CLI to provide an easier experience for managing Google Cloud Managed Instance Groups.\n\n## Features\n\n- List MIGs in your project\n- Spin up/down VMs with exact custom names (auto-detects gcloud beta)\n- Track your personal VMs\n- Automatic SSH config management for VS Code Remote Explorer\n- Easy file/directory uploads\n- Multi-node cluster support with coordinated naming\n\n## Installation\n\n```bash\npip install migs\n```\n\nOr to build from source:\n```bash\ngit clone https://github.com/keatonelvins/migs.git\ncd migs\npip install -e .\n```\n\n## Prerequisites\n\n- Python 3.8+\n- gcloud CLI installed and authenticated (`gcloud auth login`)\n- SSH keys configured for Google Compute Engine\n- (Optional) gcloud beta component for exact VM naming (`gcloud components install beta`)\n\n## Usage\n\n### List all MIGs\n```bash\nmigs list\n```\n\n### Spin up a VM\n```bash\n# With custom name (auto-detects gcloud beta availability)\nmigs up my-mig -n my-dev-vm # Creates VM named \"my-dev-vm\" if beta available\nmigs up my-mig -n my-dev-vm -d 2h # Auto-delete after 2 hours\nmigs up my-mig -n node -c 3 # Creates \"node1\", \"node2\", \"node3\"\n\n# Without custom name (auto-generated)\nmigs up my-mig # Creates \"my-mig-username-timestamp\"\n\n# Force stable API (bypass auto-detection)\nmigs up my-mig -n my-dev-vm --stable # Use stable API (VM gets random name, mapped locally)\n```\n\n### List your VMs\n```bash\nmigs vms\n```\n\n### Sync VM state\n```bash\nmigs sync # Sync local VM list with GCP state\nmigs sync --discover # Also discover and claim untracked VMs\n```\n\n### Check VM connectivity\n```bash\nmigs check my-dev-vm # Test SSH connectivity\n```\n\n### SSH into a VM\n```bash\nmigs ssh my-dev-vm\nmigs ssh my-dev-vm -- tmux attach # Pass additional SSH arguments\n```\n\n### Run scripts\n```bash\nmigs run my-dev-vm ./setup.sh # Runs in tmux session\nmigs run my-dev-vm ./deploy.sh --session deploy # Custom session name\nmigs run my-dev-vm ./script.sh arg1 arg2 # Pass arguments to script\n```\n\n### Environment Variables (.env files)\nBoth `ssh` and `run` commands automatically detect and use `.env` files from your current directory:\n\n```bash\n# If .env exists in current directory, it will be uploaded and sourced\nmigs ssh my-dev-vm # Variables from .env available in shell\nmigs run my-dev-vm ./app.sh # Script runs with .env variables\n```\n\nThe `.env` file is uploaded to `/tmp/.env` on the VM and sourced using `set -a; source /tmp/.env; set +a` to export all variables.\n\nIf `$GITHUB_TOKEN` exists in your `.env`, will also configure the gh cli.\n\n### Upload files\n```bash\nmigs upload my-dev-vm ./myfile.txt\nmigs upload my-dev-vm ./mydir/ /home/user/\n```\n\n### Download files\n```bash\nmigs download my-dev-vm /remote/file.txt\nmigs download my-dev-vm /remote/dir/ ./local/\n```\n\n### Spin down a VM\n```bash\nmigs down my-dev-vm\n```\n\n### Multi-Node Cluster\n```bash\n# Create 4-node cluster with coordinated names\nmigs up my-mig --name cluster -c 4 # Creates cluster1, cluster2, cluster3, cluster4\n\n# SSH to specific nodes\nmigs ssh cluster1\nmigs ssh cluster2\n\n# Run script on all nodes\nmigs run cluster train.py --all\n\n# Shut down entire cluster\nmigs down cluster --all\n```\n\n### Distributed Training (PyTorch)\nThe `--torchrun` flag automatically sets up environment variables for distributed training:\n\n```bash\n# Run distributed training script on all nodes\nmigs run cluster train.py --all --torchrun\n\n# This automatically sets on each node:\n- HEAD_NODE_IP: Internal IP of cluster1 (head node)\n- HEAD_NODE_PORT: 5000\n- NNODES: Total number of nodes\n- NODE_RANK: 0 for head, 1+ for workers\n- NPROC_PER_NODE: Auto-detected GPU count\n\n# Your script can then use torchrun:\ntorchrun --nproc_per_node=$NPROC_PER_NODE \\\n --nnodes=$NNODES \\\n --node_rank=$NODE_RANK \\\n --master_addr=$HEAD_NODE_IP \\\n --master_port=$HEAD_NODE_PORT \\\n your_training_script.py\n```\n\n## SSH Config\n\nThe tool automatically updates your `~/.ssh/config` file with entries for your VMs, making them accessible in VS Code Remote Explorer.\n\n# Release Instructions\n### Setup and Installation\n```bash\n# Install development dependencies and tool in editable mode\nmake dev-install\n# Or directly with pip\npip install -e .\n\n# Install packaging tools (needed for building/releasing)\nmake install-tools\n```\n\n### Building and Testing\n```bash\n# Build distribution packages\nmake build\n\n# Clean build artifacts\nmake clean\n```\n\n### Release Process\nFirst increment the `pyproject.toml` and `src/migs/__init__.py`\n```bash\n# Test upload to PyPI\nmake test-upload\n\n# Full release (clean, build, upload)\nmake release\n```\n\nAdd git version tag:\n```bash\ngit tag v0.1.x\ngit push origin v0.1.x\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "CLI tool for managing Google Cloud Managed Instance Groups",
"version": "0.1.7",
"project_urls": {
"Documentation": "https://github.com/keatonelvins/migs#readme",
"Homepage": "https://github.com/keatonelvins/migs",
"Issues": "https://github.com/keatonelvins/migs/issues",
"Repository": "https://github.com/keatonelvins/migs.git"
},
"split_keywords": [
"gcloud",
" google-cloud",
" mig",
" managed-instance-groups",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2a1df78dd209b603d4b547614a50300cda20862a1487bceab6e07bfc5e91c73c",
"md5": "a18451f0fbe522f5f247c3d21b2a2568",
"sha256": "5a31799db26200b87945046336e88f8e1d99b2d6c459610a55eb27604ee2fea7"
},
"downloads": -1,
"filename": "migs-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a18451f0fbe522f5f247c3d21b2a2568",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18221,
"upload_time": "2025-08-28T21:41:38",
"upload_time_iso_8601": "2025-08-28T21:41:38.710885Z",
"url": "https://files.pythonhosted.org/packages/2a/1d/f78dd209b603d4b547614a50300cda20862a1487bceab6e07bfc5e91c73c/migs-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "93a24d9e54c279225fee34276ee6c38e1a9f88b4b391178d4970d42660602cdf",
"md5": "ace8a06a453a2b63ea2712e6f4183027",
"sha256": "db2d90012d148d49e186d4f09f1a4042655d3b3bd01c841aae0e562715e42370"
},
"downloads": -1,
"filename": "migs-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "ace8a06a453a2b63ea2712e6f4183027",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19098,
"upload_time": "2025-08-28T21:41:40",
"upload_time_iso_8601": "2025-08-28T21:41:40.290523Z",
"url": "https://files.pythonhosted.org/packages/93/a2/4d9e54c279225fee34276ee6c38e1a9f88b4b391178d4970d42660602cdf/migs-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 21:41:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "keatonelvins",
"github_project": "migs#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "migs"
}
JSON
