From 3761c08fba7a0faf66384c6c7dbbe13d3826783b Mon Sep 17 00:00:00 2001 From: Matt Linville Date: Wed, 19 Nov 2025 16:44:52 -0800 Subject: [PATCH 1/2] Update script for Mintlify --- scripts/cli-docs-generator.py | 758 ++++++++++++++++++++++++++++++++++ 1 file changed, 758 insertions(+) create mode 100755 scripts/cli-docs-generator.py diff --git a/scripts/cli-docs-generator.py b/scripts/cli-docs-generator.py new file mode 100755 index 0000000000..fb9b004510 --- /dev/null +++ b/scripts/cli-docs-generator.py @@ -0,0 +1,758 @@ +#!/usr/bin/env python3 +""" +Generate Mintlify-compatible markdown documentation for W&B CLI commands. + +This script automatically generates reference documentation for the W&B CLI +by introspecting the Click-based command structure. It creates properly +formatted markdown files with Mintlify front matter for use in the documentation site. + +Note: Launch-only commands (launch, launch-agent, launch-sweep, scheduler) are generated +but excluded from the docs.json navigation (hidden from sidebar). + +Usage: + python scripts/cli-docs-generator.py # Auto-overwrites existing docs (default) + python scripts/cli-docs-generator.py -i # Interactive mode (prompts for confirmation) + python scripts/cli-docs-generator.py -o PATH # Custom output directory + + Options: + -i, --interactive Prompt for confirmation before overwriting + -o, --output Custom output directory (default: models/ref/cli/) + +Output: + Generated documentation will be placed in: models/ref/cli/ (by default) + Navigation structure will be updated in: docs.json + +Requirements: + - wandb package must be installed (pip install wandb) + - Must be run from the project root directory + +""" + +import os +import re +import sys +import argparse +import shutil +import json +from pathlib import Path +from typing import Dict, Any, List, Optional, Union +import click +from click.core import Command, Group + +def clean_text(text: str) -> str: + """Clean and format text for markdown.""" + if not text: + return "" + + # First, normalize line endings and strip the whole text + text = text.strip() + + # Split into paragraphs (separated by blank lines) + paragraphs = re.split(r'\n\s*\n', text) + + # Clean each paragraph: remove extra spaces within lines, but keep paragraph structure + cleaned_paragraphs = [] + for paragraph in paragraphs: + # Replace multiple spaces/tabs with single space, but keep newlines + lines = paragraph.split('\n') + cleaned_lines = [] + for line in lines: + # Clean up spaces within the line + cleaned_line = re.sub(r'[ \t]+', ' ', line.strip()) + if cleaned_line: # Only add non-empty lines + cleaned_lines.append(cleaned_line) + if cleaned_lines: + cleaned_paragraphs.append(' '.join(cleaned_lines)) + + # Join paragraphs with double newlines for markdown + text = '\n\n'.join(cleaned_paragraphs) + + # Escape pipe characters for markdown tables + text = text.replace('|', '\\|') + return text + +def get_brief_description(text: str) -> str: + """Get just the first sentence or line for table display.""" + if not text: + return "No description available" + + # First clean the text but without escaping pipes yet + text = text.strip() + + # Split into paragraphs + paragraphs = re.split(r'\n\s*\n', text) + if not paragraphs: + return "No description available" + + # Get the first paragraph + first_para = paragraphs[0] + + # Clean up spaces in the first paragraph + first_para = re.sub(r'[ \t\n]+', ' ', first_para.strip()) + + # Try to get just the first sentence + # Look for sentence endings + sentence_match = re.match(r'^(.*?[.!?])\s', first_para + ' ') + if sentence_match: + first_sentence = sentence_match.group(1) + else: + # If no sentence ending found, take the whole first paragraph + # but limit to reasonable length + first_sentence = first_para + + # Limit length for table display + max_length = 150 + if len(first_sentence) > max_length: + first_sentence = first_sentence[:max_length-3] + "..." + + # Escape pipe characters for markdown tables + first_sentence = first_sentence.replace('|', '\\|') + + return first_sentence + +def get_param_info(param) -> Dict[str, Any]: + """Extract parameter information from a Click parameter.""" + # Check if it's an Option or Argument + is_option = isinstance(param, click.Option) + + info = { + 'name': param.name, + 'opts': getattr(param, 'opts', []) or [], + 'help': clean_text(getattr(param, 'help', '') or ''), + 'type': str(param.type) if hasattr(param, 'type') else 'TEXT', + 'required': getattr(param, 'required', False), + 'default': getattr(param, 'default', None), + 'multiple': getattr(param, 'multiple', False), + } + + # Format options string + if info['opts']: + info['opts_str'] = ', '.join(f'`{opt}`' for opt in info['opts']) + else: + info['opts_str'] = f'`{info["name"]}`' + + # Format default value + if info['default'] is not None and info['default'] != () and not callable(info['default']): + info['default_str'] = f" (default: {info['default']})" + else: + info['default_str'] = "" + + return info + +def extract_command_info(cmd: Command, parent_name: str = "") -> Dict[str, Any]: + """Extract information from a Click command.""" + # Launch-only commands to exclude from docs.json navigation + LAUNCH_COMMANDS = {'launch', 'launch-agent', 'launch-sweep', 'scheduler'} + + # For the root command, use "wandb" as the name + name = cmd.name if cmd.name else "wandb" + full_name = f"{parent_name} {name}".strip() if parent_name else name + + info = { + 'name': name, + 'full_name': full_name, + 'help': clean_text(cmd.help or cmd.short_help or ''), + 'epilog': clean_text(cmd.epilog) if hasattr(cmd, 'epilog') and cmd.epilog else '', + 'params': [], + 'options': [], + 'arguments': [], + 'subcommands': {}, + 'is_group': isinstance(cmd, Group), + 'is_launch_command': name in LAUNCH_COMMANDS, + } + + # Extract parameters + for param in cmd.params: + param_info = get_param_info(param) + if isinstance(param, click.Option): + info['options'].append(param_info) + elif isinstance(param, click.Argument): + info['arguments'].append(param_info) + + # Extract subcommands if it's a group + if isinstance(cmd, Group): + for name, subcmd in cmd.commands.items(): + info['subcommands'][name] = extract_command_info(subcmd, full_name) + + return info + +def generate_markdown(cmd_info: Dict[str, Any], file_dir_path: str = "") -> str: + """Generate markdown content for a command. + + Args: + cmd_info: Command information dictionary + file_dir_path: Directory path where this file will be located (e.g., "wandb-artifact" for files in that dir) + """ + lines = [] + + # Mintlify front matter (simple, no Hugo properties) + lines.append("---") + # Fix title to show 'wandb' instead of 'cli' + title = cmd_info['full_name'].replace('cli', 'wandb') + lines.append(f"title: {title}") + lines.append("---") + lines.append("") + + # Command description + if cmd_info['help']: + lines.append(cmd_info['help']) + lines.append("") + + # Usage section + lines.append("## Usage") + lines.append("") + lines.append("```bash") + + # Fix usage to always show 'wandb' as the base command + if cmd_info['name'] in ['wandb', 'cli']: + usage = "wandb" + else: + usage = f"wandb {cmd_info['name']}" + + # Add arguments to usage + for arg in cmd_info['arguments']: + if arg['required']: + usage += f" {arg['name'].upper()}" + else: + usage += f" [{arg['name'].upper()}]" + + # Add [OPTIONS] if there are options + if cmd_info['options']: + usage += " [OPTIONS]" + + # Add subcommand placeholder if it's a group + if cmd_info['is_group'] and cmd_info['subcommands']: + usage += " COMMAND [ARGS]..." + + lines.append(usage) + lines.append("```") + lines.append("") + + # Arguments section + if cmd_info['arguments']: + lines.append("## Arguments") + lines.append("") + lines.append("| Argument | Description | Required |") + lines.append("| :--- | :--- | :--- |") + for arg in cmd_info['arguments']: + required = "Yes" if arg['required'] else "No" + desc = arg['help'] or "No description available" + lines.append(f"| `{arg['name'].upper()}` | {desc} | {required} |") + lines.append("") + + # Options section + if cmd_info['options']: + lines.append("## Options") + lines.append("") + lines.append("| Option | Description |") + lines.append("| :--- | :--- |") + for opt in cmd_info['options']: + desc = opt['help'] or "No description available" + if opt['default_str']: + desc += opt['default_str'] + lines.append(f"| {opt['opts_str']} | {desc} |") + lines.append("") + + # Subcommands section + if cmd_info['is_group'] and cmd_info['subcommands']: + lines.append("## Commands") + lines.append("") + lines.append("| Command | Description |") + lines.append("| :--- | :--- |") + for name, subcmd_info in sorted(cmd_info['subcommands'].items()): + # Use brief description for table display + desc = get_brief_description(subcmd_info['help'] or "") + # For nested commands, we need to determine the correct reference path + # Get the full parent prefix from the full_name + parent_parts = cmd_info['full_name'].replace('cli', 'wandb').split() + parent_prefix = '-'.join(parent_parts) + # Subcommands are in a subdirectory named after the parent + # Build the full path including the directory this file is in + if file_dir_path: + full_path = f"/models/ref/cli/{file_dir_path}/{parent_prefix}/{parent_prefix}-{name}" + else: + full_path = f"/models/ref/cli/{parent_prefix}/{parent_prefix}-{name}" + lines.append(f"| [{name}]({full_path}) | {desc} |") + lines.append("") + + # Epilog section + if cmd_info['epilog']: + lines.append("## Additional Information") + lines.append("") + lines.append(cmd_info['epilog']) + lines.append("") + + return "\n".join(lines) + +def generate_index_markdown(cmd_info: Dict[str, Any], subcommands_only: bool = False, content_before: str = None, content_after: str = None, file_dir_path: str = "") -> str: + """Generate index markdown for a command group. + + Args: + cmd_info: Command information dictionary + subcommands_only: Whether this is a subcommand index page + content_before: Manual content to preserve before auto-generated content + content_after: Manual content to preserve after auto-generated content + file_dir_path: Directory path where this file will be located (e.g., "wandb-artifact" for files in that dir) + """ + lines = [] + + # Mintlify front matter (simple, no Hugo properties) + lines.append("---") + if subcommands_only: + # For subcommand index pages + title = f"{cmd_info['full_name']}".replace('cli', 'wandb') + lines.append(f"title: {title}") + else: + lines.append("title: CLI overview") + lines.append("description: Use the W&B Command Line Interface (CLI) to log in, run jobs, execute sweeps, and more using shell commands") + lines.append("---") + lines.append("") + + # Insert preserved manual content before auto-generated content + if content_before: + lines.append(content_before) + lines.append("") + + # Auto-generated marker start (for main CLI page only) + if not subcommands_only: + lines.append("{/* AUTO-GENERATED CONTENT STARTS HERE */}") + lines.append("{/* WARNING: Do not edit below this line. This content is auto-generated by scripts/cli-docs-generator.py */}") + lines.append("") + + # Description (only if no preserved content) + if not content_before and cmd_info['help']: + lines.append(cmd_info['help']) + lines.append("") + + # Usage section + lines.append("## Basic Usage" if content_before else "## Usage") + lines.append("") + lines.append("```bash") + # Always use 'wandb' as the base command + if cmd_info['name'] in ['wandb', 'cli']: + usage = "wandb" + else: + usage = cmd_info['full_name'].replace('cli', 'wandb') + if cmd_info['options']: + usage += " [OPTIONS]" + if cmd_info['is_group'] and cmd_info['subcommands']: + usage += " COMMAND [ARGS]..." + lines.append(usage) + lines.append("```") + lines.append("") + + # Options section (for main command) + if cmd_info['options']: + lines.append("## Options") + lines.append("") + lines.append("| Option | Description |") + lines.append("| :--- | :--- |") + for opt in cmd_info['options']: + desc = opt['help'] or "No description available" + if opt['default_str']: + desc += opt['default_str'] + lines.append(f"| {opt['opts_str']} | {desc} |") + lines.append("") + + # Commands section + if cmd_info['is_group'] and cmd_info['subcommands']: + lines.append("## Commands") + lines.append("") + lines.append("| Command | Description |") + lines.append("| :--- | :--- |") + for name, subcmd_info in sorted(cmd_info['subcommands'].items()): + # Use brief description for table display + desc = get_brief_description(subcmd_info['help'] or "") + # Link to the command page using absolute Mintlify paths + if subcommands_only: + # Get the full parent prefix from the full_name + parent_parts = cmd_info['full_name'].replace('cli', 'wandb').split() + parent_prefix = '-'.join(parent_parts) + # Subcommands are in a subdirectory named after the parent command + # The subdirectory is named {parent_prefix} and contains files named {parent_prefix}-{name} + if file_dir_path: + full_path = f"/models/ref/cli/{file_dir_path}/{parent_prefix}/{parent_prefix}-{name}" + else: + full_path = f"/models/ref/cli/{parent_prefix}/{parent_prefix}-{name}" + lines.append(f"| [{name}]({full_path}) | {desc} |") + else: + # Top-level commands from main CLI page + lines.append(f"| [{name}](/models/ref/cli/wandb-{name}) | {desc} |") + lines.append("") + + # Auto-generated marker end and preserved content after + if not subcommands_only: + lines.append("{/* AUTO-GENERATED CONTENT ENDS HERE */}") + if content_after: + lines.append("{/* Manual content continues below */}") + lines.append("") + lines.append(content_after) + + return "\n".join(lines) + +def extract_manual_content(file_path: Path) -> tuple[Optional[str], Optional[str]]: + """Extract manually written content from existing cli.mdx file. + + Returns a tuple of (content_before, content_after) where: + - content_before: Content between front matter and auto-generated marker + - content_after: Content after the auto-generated section ends + Both can be None if the file doesn't exist or has no manual content. + """ + if not file_path.exists(): + return (None, None) + + with open(file_path, 'r') as f: + content = f.read() + + # Find the end of front matter + if not content.startswith('---'): + return (None, None) + + # Find the second '---' that ends the front matter + front_matter_end = content.find('---', 3) + if front_matter_end == -1: + return (None, None) + + # Move past the closing --- and newline + content_start = front_matter_end + 3 + while content_start < len(content) and content[content_start] in ['\n', '\r']: + content_start += 1 + + # Find the auto-generated markers (JSX-style comments for MDX) + auto_gen_start_marker = "{/* AUTO-GENERATED CONTENT STARTS HERE */}" + auto_gen_end_marker = "{/* AUTO-GENERATED CONTENT ENDS HERE */}" + + auto_gen_start = content.find(auto_gen_start_marker) + auto_gen_end = content.find(auto_gen_end_marker) + + content_before = None + content_after = None + + if auto_gen_start == -1: + # No marker found, check if there's a "## Usage" or "## Basic Usage" section + usage_match = re.search(r'\n## (?:Basic )?Usage\n', content) + if usage_match: + # Content before Usage section is likely manual + content_before = content[content_start:usage_match.start()].strip() + else: + # Extract content between front matter and auto-generated marker + content_before = content[content_start:auto_gen_start].strip() + + # If we have an end marker, extract content after it + if auto_gen_end != -1: + # Find content after the end marker and following comment line + content_after_start = content.find('\n', auto_gen_end) + 1 + # Skip the "Manual content continues below" comment if present + manual_comment = "{/* Manual content continues below */}" + if content[content_after_start:].strip().startswith(manual_comment): + content_after_start = content.find('\n', content_after_start + len(manual_comment)) + 1 + + remaining = content[content_after_start:].strip() + if remaining: + content_after = remaining + + return (content_before, content_after) + +def write_command_docs(cmd_info: Dict[str, Any], output_dir: Path, parent_path: str = "", file_dir_path: str = ""): + """Write documentation files for a command and its subcommands. + + For Mintlify, the structure is: + - Root: cli.mdx (main index) in models/ref/ + - Command groups: wandb-artifact.mdx (group file) + wandb-artifact/ (directory for subcommands) + - Simple commands: wandb-login.mdx (single file) + - Nested in directories: wandb-artifact/wandb-artifact-get.mdx + + Args: + cmd_info: Command information dictionary + output_dir: Base output directory for files + parent_path: Accumulated path prefix for file naming (e.g., "artifact-" for cache in artifact) + file_dir_path: Directory path where files are located relative to models/ref/cli/ (e.g., "wandb-artifact") + """ + cmd_name = cmd_info['name'] + + # Check if this is the root wandb command (either 'cli' or 'wandb' or None) + is_root = cmd_name in ['wandb', 'cli', None] and parent_path == "" + + if is_root: + # Main CLI index - Mintlify wants cli.mdx in models/ref/ + index_path = output_dir.parent / "cli.mdx" + + # Extract any existing manual content before regenerating + content_before, content_after = extract_manual_content(index_path) + + index_path.parent.mkdir(parents=True, exist_ok=True) + with open(index_path, 'w') as f: + f.write(generate_index_markdown(cmd_info, content_before=content_before, content_after=content_after, file_dir_path="")) + print(f"Generated: {index_path}") + if content_before or content_after: + print(f" ✓ Preserved manual content") + + # Process top-level commands (alphabetically sorted) + for name, subcmd_info in sorted(cmd_info['subcommands'].items()): + write_command_docs(subcmd_info, output_dir, "", "") + else: + # Determine if this command has subcommands + has_subcommands = cmd_info['is_group'] and cmd_info['subcommands'] + + if has_subcommands: + # For command groups, create BOTH a .mdx file AND a directory + # The .mdx file serves as the group page + cmd_file_name = f"wandb-{parent_path}{cmd_name}" + cmd_file_path = output_dir / f"{cmd_file_name}.mdx" + with open(cmd_file_path, 'w') as f: + f.write(generate_index_markdown(cmd_info, subcommands_only=True, file_dir_path=file_dir_path)) + print(f"Generated: {cmd_file_path}") + + # Create the directory for subcommands + cmd_dir = output_dir / cmd_file_name + cmd_dir.mkdir(parents=True, exist_ok=True) + + # Calculate the new file_dir_path for subcommands (append this directory to the path) + if file_dir_path: + new_file_dir_path = f"{file_dir_path}/{cmd_file_name}" + else: + new_file_dir_path = cmd_file_name + + # Write individual subcommand files (alphabetically sorted) + for subcmd_name, subcmd_info in sorted(cmd_info['subcommands'].items()): + # Check if this subcommand also has subcommands + if subcmd_info['is_group'] and subcmd_info['subcommands']: + # Handle nested command groups recursively + write_command_docs(subcmd_info, cmd_dir, f"{parent_path}{cmd_name}-", new_file_dir_path) + else: + # Write single subcommand file in the directory + subcmd_path = cmd_dir / f"wandb-{parent_path}{cmd_name}-{subcmd_name}.mdx" + with open(subcmd_path, 'w') as f: + f.write(generate_markdown(subcmd_info, file_dir_path=new_file_dir_path)) + print(f"Generated: {subcmd_path}") + else: + # Write single command file + cmd_path = output_dir / f"wandb-{parent_path}{cmd_name}.mdx" + with open(cmd_path, 'w') as f: + f.write(generate_markdown(cmd_info, file_dir_path=file_dir_path)) + print(f"Generated: {cmd_path}") + +def build_nav_structure(cmd_info: Dict[str, Any], parent_path: str = "") -> List[Union[str, Dict[str, Any]]]: + """Build navigation structure for docs.json, excluding launch commands. + + Returns a list of navigation items (either strings for simple pages or dicts for groups). + """ + nav_items = [] + + if not cmd_info['is_group'] or not cmd_info['subcommands']: + return nav_items + + for name, subcmd_info in sorted(cmd_info['subcommands'].items()): + # Skip launch commands in navigation + if subcmd_info.get('is_launch_command', False): + continue + + # Build the path for this command + if parent_path: + path = f"{parent_path}-{name}" + else: + path = f"wandb-{name}" + + if subcmd_info['is_group'] and subcmd_info['subcommands']: + # This is a group with subcommands + subpages = [] + + # IMPORTANT: Include the group's own page first! + # This is the wandb-{name}.mdx file that serves as the group overview + subpages.append(f"models/ref/cli/{path}") + + # Recursively build subcommand navigation + for subname, subinfo in sorted(subcmd_info['subcommands'].items()): + # Skip launch commands + if subinfo.get('is_launch_command', False): + continue + + subpath = f"{path}-{subname}" + + if subinfo['is_group'] and subinfo['subcommands']: + # Nested group - needs its own page plus subpages + nested_pages = [] + # Include the nested group's own page first + nested_pages.append(f"models/ref/cli/{path}/{subpath}") + # Then add its subcommands + for nestedname, nestedinfo in sorted(subinfo['subcommands'].items()): + if nestedinfo.get('is_launch_command', False): + continue + nested_pages.append(f"models/ref/cli/{path}/{subpath}/{subpath}-{nestedname}") + + if nested_pages: + subpages.append({ + "group": f"{name} {subname}", + "pages": nested_pages + }) + else: + # Simple subcommand + subpages.append(f"models/ref/cli/{path}/{subpath}") + + if subpages: + nav_items.append({ + "group": f"wandb {name}", + "pages": subpages + }) + else: + # Simple command + nav_items.append(f"models/ref/cli/{path}") + + return nav_items + + +def update_docs_json(project_root: Path, nav_items: List[Union[str, Dict[str, Any]]]): + """Update docs.json with the new CLI navigation structure.""" + docs_json_path = project_root / "docs.json" + + if not docs_json_path.exists(): + print(f"❌ Error: docs.json not found at {docs_json_path}") + return False + + try: + with open(docs_json_path, 'r') as f: + docs_data = json.load(f) + + # Find the CLI section in the navigation + # It's nested under navigation -> pages -> (some models section) -> pages -> CLI group + found = False + + def find_and_update_cli(obj): + """Recursively find and update the CLI section.""" + nonlocal found + + if isinstance(obj, dict): + if obj.get('group') == 'Command Line Interface (CLI)': + # Found it! Update the pages + obj['pages'] = ["models/ref/cli"] + nav_items + found = True + return True + + # Recurse into nested structures + for key, value in obj.items(): + if find_and_update_cli(value): + return True + + elif isinstance(obj, list): + for item in obj: + if find_and_update_cli(item): + return True + + return False + + find_and_update_cli(docs_data) + + if not found: + print("⚠️ Warning: Could not find 'Command Line Interface (CLI)' section in docs.json") + return False + + # Write back to docs.json + with open(docs_json_path, 'w') as f: + json.dump(docs_data, f, indent=2) + + print(f"✅ Updated docs.json with CLI navigation (excluded launch commands)") + return True + + except json.JSONDecodeError as e: + print(f"❌ Error: Could not parse docs.json: {e}") + return False + except Exception as e: + print(f"❌ Error updating docs.json: {e}") + return False + + +def main(): + """Main function to generate CLI documentation.""" + # Parse command-line arguments + parser = argparse.ArgumentParser(description='Generate W&B CLI documentation') + parser.add_argument('-i', '--interactive', action='store_true', + help='Prompt for confirmation before overwriting existing documentation') + parser.add_argument('-o', '--output', type=str, default=None, + help='Custom output directory (default: models/ref/cli)') + args = parser.parse_args() + + # Get the script's parent directory (scripts/) and then go up to the project root + script_dir = Path(__file__).parent + project_root = script_dir.parent + + if args.output: + output_dir = Path(args.output) + else: + output_dir = project_root / "models" / "ref" / "cli" + + print("Generating W&B CLI documentation...") + print(f"Output directory: {output_dir}") + + # Warning about overwriting existing documentation (only in interactive mode) + if output_dir.exists() and any(output_dir.iterdir()): + # Check if cli.mdx has manual content (Mintlify structure) + index_path = output_dir.parent / "cli.mdx" + content_before, content_after = extract_manual_content(index_path) + has_manual_content = content_before is not None or content_after is not None + + if args.interactive: + print(f"⚠️ Warning: This will regenerate documentation in {output_dir}") + if has_manual_content: + print(" Note: Manual content in cli.mdx will be preserved.") + response = input("Continue? (y/N): ") + if response.lower() != 'y': + print("Aborted.") + sys.exit(0) + + # Clear directory selectively to remove any vestigial files from removed commands + print("Clearing existing documentation...") + files_removed = 0 + dirs_removed = 0 + for item in output_dir.iterdir(): + if item.is_file(): + item.unlink() + files_removed += 1 + elif item.is_dir(): + shutil.rmtree(item) + dirs_removed += 1 + print(f" Removed {files_removed} files and {dirs_removed} directories") + + # Create output directory + output_dir.mkdir(parents=True, exist_ok=True) + + try: + # Import W&B CLI - the cli module contains a Click group called 'cli' + from wandb.cli.cli import cli as wandb_cli + + # Extract command information + print("Extracting CLI structure...") + cli_info = extract_command_info(wandb_cli) + + # Generate documentation files + print("Generating markdown files...") + write_command_docs(cli_info, output_dir) + + print(f"\n✅ Documentation generated successfully in {output_dir}") + # Count both .mdx files in output_dir and the cli.mdx in parent + mdx_files = list(output_dir.rglob('*.mdx')) + cli_index = output_dir.parent / "cli.mdx" + if cli_index.exists(): + mdx_files.append(cli_index) + print(f"Total files generated: {len(mdx_files)}") + + # Update docs.json with navigation structure + print("\nUpdating docs.json...") + nav_items = build_nav_structure(cli_info) + if update_docs_json(project_root, nav_items): + print("✅ Navigation structure updated (Launch commands excluded from TOC)") + else: + print("⚠️ Warning: Could not update docs.json navigation") + + except ImportError as e: + print(f"❌ Error: Could not import wandb CLI. Make sure wandb is installed.") + print(f" Run: pip install wandb") + print(f" Error details: {e}") + sys.exit(1) + except Exception as e: + print(f"❌ Unexpected error: {e}") + import traceback + traceback.print_exc() + sys.exit(1) + +if __name__ == "__main__": + main() From 98af6796936f267d8c8083daf43f209347a955fe Mon Sep 17 00:00:00 2001 From: Matt Linville Date: Wed, 19 Nov 2025 17:11:58 -0800 Subject: [PATCH 2/2] Regenerate refs for 0.23.0 --- docs.json | 22 +++--- models/ref/cli.mdx | 35 ++++++---- models/ref/cli/wandb-agent.mdx | 26 +++---- models/ref/cli/wandb-artifact.mdx | 48 ++++++------- .../wandb-artifact/wandb-artifact-cache.mdx | 42 +++++------- .../wandb-artifact-cache-cleanup.mdx | 24 ++++--- .../cli/wandb-artifact/wandb-artifact-get.mdx | 22 +++--- .../cli/wandb-artifact/wandb-artifact-ls.mdx | 24 ++++--- .../cli/wandb-artifact/wandb-artifact-put.mdx | 36 +++++----- models/ref/cli/wandb-beta.mdx | 45 ++++++------- models/ref/cli/wandb-beta/wandb-beta-sync.mdx | 41 +++++++----- models/ref/cli/wandb-controller.mdx | 24 ++++--- models/ref/cli/wandb-disabled.mdx | 22 +++--- models/ref/cli/wandb-docker-run.mdx | 27 +++----- models/ref/cli/wandb-docker.mdx | 58 +++++++--------- models/ref/cli/wandb-enabled.mdx | 22 +++--- models/ref/cli/wandb-init.mdx | 28 ++++---- models/ref/cli/wandb-job.mdx | 46 ++++++------- models/ref/cli/wandb-job/wandb-job-create.mdx | 51 +++++++------- .../ref/cli/wandb-job/wandb-job-describe.mdx | 24 +++---- models/ref/cli/wandb-job/wandb-job-list.mdx | 24 +++---- models/ref/cli/wandb-launch-agent.mdx | 33 +++++---- models/ref/cli/wandb-launch-sweep.mdx | 32 ++++----- models/ref/cli/wandb-launch.mdx | 59 ++++++++-------- models/ref/cli/wandb-login.mdx | 34 ++++++---- models/ref/cli/wandb-offline.mdx | 21 ++---- models/ref/cli/wandb-online.mdx | 21 ++---- models/ref/cli/wandb-pull.mdx | 26 +++---- models/ref/cli/wandb-restore.mdx | 32 ++++----- models/ref/cli/wandb-scheduler.mdx | 21 +++--- models/ref/cli/wandb-server.mdx | 44 +++++------- .../cli/wandb-server/wandb-server-start.mdx | 28 ++++---- .../cli/wandb-server/wandb-server-stop.mdx | 19 ++---- models/ref/cli/wandb-status.mdx | 22 +++--- models/ref/cli/wandb-sweep.mdx | 44 ++++++------ models/ref/cli/wandb-sync.mdx | 67 ++++++++++++------- models/ref/cli/wandb-verify.mdx | 44 +++++------- 37 files changed, 591 insertions(+), 647 deletions(-) diff --git a/docs.json b/docs.json index 59ce4aa4c6..c9eb9f622e 100644 --- a/docs.json +++ b/docs.json @@ -623,9 +623,11 @@ { "group": "wandb artifact", "pages": [ + "models/ref/cli/wandb-artifact", { - "group": "wandb artifact cache", + "group": "artifact cache", "pages": [ + "models/ref/cli/wandb-artifact/wandb-artifact-cache", "models/ref/cli/wandb-artifact/wandb-artifact-cache/wandb-artifact-cache-cleanup" ] }, @@ -637,6 +639,8 @@ { "group": "wandb beta", "pages": [ + "models/ref/cli/wandb-beta", + "models/ref/cli/wandb-beta/wandb-beta-leet", "models/ref/cli/wandb-beta/wandb-beta-sync" ] }, @@ -649,23 +653,25 @@ { "group": "wandb job", "pages": [ + "models/ref/cli/wandb-job", "models/ref/cli/wandb-job/wandb-job-create", "models/ref/cli/wandb-job/wandb-job-describe", "models/ref/cli/wandb-job/wandb-job-list" ] }, - "models/ref/cli/wandb-launch", - "models/ref/cli/wandb-launch-agent", - "models/ref/cli/wandb-launch-sweep", + "models/ref/cli/wandb-local", "models/ref/cli/wandb-login", + "models/ref/cli/wandb-off", "models/ref/cli/wandb-offline", + "models/ref/cli/wandb-on", "models/ref/cli/wandb-online", + "models/ref/cli/wandb-projects", "models/ref/cli/wandb-pull", "models/ref/cli/wandb-restore", - "models/ref/cli/wandb-scheduler", { "group": "wandb server", "pages": [ + "models/ref/cli/wandb-server", "models/ref/cli/wandb-server/wandb-server-start", "models/ref/cli/wandb-server/wandb-server-stop" ] @@ -2299,7 +2305,7 @@ { "source": "/guides/integrations/pytorch", "destination": "/models/integrations" - }, + }, { "source": "/guides/launch/:slug*", "destination": "/platform/launch/:slug*" @@ -2307,7 +2313,7 @@ { "source": "/models/registry/model_registry/:slug*", "destination": "/models/registry" - }, + }, { "source": "/guides/registry/:slug*", "destination": "/models/registry/:slug*" @@ -2490,4 +2496,4 @@ } ], "baseUrl": "https://docs.wandb.ai" -} +} \ No newline at end of file diff --git a/models/ref/cli.mdx b/models/ref/cli.mdx index 09cef30ae0..3f762b2a2f 100644 --- a/models/ref/cli.mdx +++ b/models/ref/cli.mdx @@ -3,22 +3,24 @@ title: CLI overview description: Use the W&B Command Line Interface (CLI) to log in, run jobs, execute sweeps, and more using shell commands --- -**Usage** +{/* AUTO-GENERATED CONTENT STARTS HERE */} +{/* WARNING: Do not edit below this line. This content is auto-generated by scripts/cli-docs-generator.py */} -`wandb [OPTIONS] COMMAND [ARGS]...` +## Usage +```bash +wandb [OPTIONS] COMMAND [ARGS]... +``` +## Options -**Options** - -| **Option** | **Description** | +| Option | Description | | :--- | :--- | -| `--version` | Show the version and exit. | - +| `--version` | Show the version and exit. (default: False) | -**Commands** +## Commands -| **Command** | **Description** | +| Command | Description | | :--- | :--- | | [agent](/models/ref/cli/wandb-agent) | Run the W&B agent | | [artifact](/models/ref/cli/wandb-artifact) | Commands for interacting with artifacts | @@ -26,22 +28,27 @@ description: Use the W&B Command Line Interface (CLI) to log in, run jobs, execu | [controller](/models/ref/cli/wandb-controller) | Run the W&B local sweep controller | | [disabled](/models/ref/cli/wandb-disabled) | Disable W&B. | | [docker](/models/ref/cli/wandb-docker) | Run your code in a docker container. | -| [docker-run](/models/ref/cli/wandb-docker-run) | Wrap `docker run` and adds WANDB_API_KEY and WANDB_DOCKER... | +| [docker-run](/models/ref/cli/wandb-docker-run) | Wrap `docker run` and adds WANDB_API_KEY and WANDB_DOCKER environment variables. | | [enabled](/models/ref/cli/wandb-enabled) | Enable W&B. | | [init](/models/ref/cli/wandb-init) | Configure a directory with Weights & Biases | | [job](/models/ref/cli/wandb-job) | Commands for managing and viewing W&B jobs | | [launch](/models/ref/cli/wandb-launch) | Launch or queue a W&B Job. | | [launch-agent](/models/ref/cli/wandb-launch-agent) | Run a W&B launch agent. | | [launch-sweep](/models/ref/cli/wandb-launch-sweep) | Run a W&B launch sweep (Experimental). | -| [login](/models/ref/cli/wandb-login) | Login to Weights & Biases | -| [offline](/models/ref/cli/wandb-offline) | Disable W&B sync | -| [online](/models/ref/cli/wandb-online) | Enable W&B sync | +| [local](/models/ref/cli/wandb-local) | Start a local W&B container (deprecated, see wandb server --help) | +| [login](/models/ref/cli/wandb-login) | Verify and store your API key for authentication with W&B services. | +| [off](/models/ref/cli/wandb-off) | No description available | +| [offline](/models/ref/cli/wandb-offline) | Save data logged to W&B locally without uploading it to the cloud. | +| [on](/models/ref/cli/wandb-on) | No description available | +| [online](/models/ref/cli/wandb-online) | Undo `wandb offline`. | +| [projects](/models/ref/cli/wandb-projects) | List projects | | [pull](/models/ref/cli/wandb-pull) | Pull files from Weights & Biases | | [restore](/models/ref/cli/wandb-restore) | Restore code, config and docker state for a run. | | [scheduler](/models/ref/cli/wandb-scheduler) | Run a W&B launch sweep scheduler (Experimental) | | [server](/models/ref/cli/wandb-server) | Commands for operating a local W&B server | | [status](/models/ref/cli/wandb-status) | Show configuration settings | | [sweep](/models/ref/cli/wandb-sweep) | Initialize a hyperparameter sweep. | -| [sync](/models/ref/cli/wandb-sync) | Upload an offline training directory to W&B | +| [sync](/models/ref/cli/wandb-sync) | Synchronize W&B run data to the cloud. | | [verify](/models/ref/cli/wandb-verify) | Checks and verifies local instance of W&B. | +{/* AUTO-GENERATED CONTENT ENDS HERE */} \ No newline at end of file diff --git a/models/ref/cli/wandb-agent.mdx b/models/ref/cli/wandb-agent.mdx index 256f22a8d9..8e4ea57c16 100644 --- a/models/ref/cli/wandb-agent.mdx +++ b/models/ref/cli/wandb-agent.mdx @@ -1,23 +1,25 @@ --- -title: "wandb agent" +title: wandb agent --- -**Usage** +Run the W&B agent -`wandb agent [OPTIONS] SWEEP_ID` +## Usage -**Summary** +```bash +wandb agent SWEEP_ID [OPTIONS] +``` -Run the W&B agent +## Arguments +| Argument | Description | Required | +| :--- | :--- | :--- | +| `SWEEP_ID` | No description available | Yes | -**Options** +## Options -| **Option** | **Description** | +| Option | Description | | :--- | :--- | -| `-p, --project` | The name of the project where W&B runs created from the sweep are sent to. If the project is not specified, the run is sent to a project labeled 'Uncategorized'. | -| `-e, --entity` | The username or team name where you want to send W&B runs created by the sweep to. Ensure that the entity you specify already exists. If you don't specify an entity, the run will be sent to your default entity, which is usually your username. | +| `--project`, `-p` | The name of the project where W&B runs created from the sweep are sent to. If the project is not specified, the run is sent to a project labeled 'Uncategorized'. | +| `--entity`, `-e` | The username or team name where you want to send W&B runs created by the sweep to. Ensure that the entity you specify already exists. If you don't specify an entity, the run will be sent to your default entity, which is usually your username. | | `--count` | The max number of runs for this agent. | - - - diff --git a/models/ref/cli/wandb-artifact.mdx b/models/ref/cli/wandb-artifact.mdx index 3b65c2ee90..38a63d643f 100644 --- a/models/ref/cli/wandb-artifact.mdx +++ b/models/ref/cli/wandb-artifact.mdx @@ -1,28 +1,20 @@ ---- -title: wandb artifact ---- - -**Usage** - -`wandb artifact [OPTIONS] COMMAND [ARGS]...` - -**Summary** - -Commands for interacting with artifacts - - -**Options** - -| **Option** | **Description** | -| :--- | :--- | - - -**Commands** - -| **Command** | **Description** | -| :--- | :--- | -| cache | Commands for interacting with the artifact cache | -| get | Download an artifact from wandb | -| ls | List all artifacts in a wandb project | -| put | Upload an artifact to wandb | - +--- +title: wandb artifact +--- + +Commands for interacting with artifacts + +## Usage + +```bash +wandb artifact COMMAND [ARGS]... +``` + +## Commands + +| Command | Description | +| :--- | :--- | +| [cache](/models/ref/cli/wandb-artifact/wandb-artifact-cache) | Commands for interacting with the artifact cache | +| [get](/models/ref/cli/wandb-artifact/wandb-artifact-get) | Download an artifact from wandb | +| [ls](/models/ref/cli/wandb-artifact/wandb-artifact-ls) | List all artifacts in a wandb project | +| [put](/models/ref/cli/wandb-artifact/wandb-artifact-put) | Upload an artifact to wandb | diff --git a/models/ref/cli/wandb-artifact/wandb-artifact-cache.mdx b/models/ref/cli/wandb-artifact/wandb-artifact-cache.mdx index 297e22e906..001688b3b7 100644 --- a/models/ref/cli/wandb-artifact/wandb-artifact-cache.mdx +++ b/models/ref/cli/wandb-artifact/wandb-artifact-cache.mdx @@ -1,25 +1,17 @@ ---- -title: wandb artifact cache ---- - -**Usage** - -`wandb artifact cache [OPTIONS] COMMAND [ARGS]...` - -**Summary** - -Commands for interacting with the artifact cache - - -**Options** - -| **Option** | **Description** | -| :--- | :--- | - - -**Commands** - -| **Command** | **Description** | -| :--- | :--- | -| cleanup | Clean up less frequently used files from the artifacts cache | - +--- +title: wandb artifact cache +--- + +Commands for interacting with the artifact cache + +## Usage + +```bash +wandb artifact cache COMMAND [ARGS]... +``` + +## Commands + +| Command | Description | +| :--- | :--- | +| [cleanup](/models/ref/cli/wandb-artifact/wandb-artifact-cache/wandb-artifact-cache-cleanup) | Clean up less frequently used files from the artifacts cache | diff --git a/models/ref/cli/wandb-artifact/wandb-artifact-cache/wandb-artifact-cache-cleanup.mdx b/models/ref/cli/wandb-artifact/wandb-artifact-cache/wandb-artifact-cache-cleanup.mdx index a787abdee7..10fc8ea4a1 100644 --- a/models/ref/cli/wandb-artifact/wandb-artifact-cache/wandb-artifact-cache-cleanup.mdx +++ b/models/ref/cli/wandb-artifact/wandb-artifact-cache/wandb-artifact-cache-cleanup.mdx @@ -1,21 +1,23 @@ --- -title: "wandb artifact cache cleanup" +title: wandb artifact cache cleanup --- -**Usage** - -`wandb artifact cache cleanup [OPTIONS] TARGET_SIZE` - -**Summary** - Clean up less frequently used files from the artifacts cache +## Usage -**Options** +```bash +wandb cleanup TARGET_SIZE [OPTIONS] +``` -| **Option** | **Description** | -| :--- | :--- | -| `--remove-temp / --no-remove-temp` | Remove temp files | +## Arguments +| Argument | Description | Required | +| :--- | :--- | :--- | +| `TARGET_SIZE` | No description available | Yes | +## Options +| Option | Description | +| :--- | :--- | +| `--remove-temp` | Remove temp files (default: False) | diff --git a/models/ref/cli/wandb-artifact/wandb-artifact-get.mdx b/models/ref/cli/wandb-artifact/wandb-artifact-get.mdx index 6693c162ad..9ac1681e42 100644 --- a/models/ref/cli/wandb-artifact/wandb-artifact-get.mdx +++ b/models/ref/cli/wandb-artifact/wandb-artifact-get.mdx @@ -1,22 +1,24 @@ --- -title: "wandb artifact get" +title: wandb artifact get --- -**Usage** +Download an artifact from wandb -`wandb artifact get [OPTIONS] PATH` +## Usage -**Summary** +```bash +wandb get PATH [OPTIONS] +``` -Download an artifact from wandb +## Arguments +| Argument | Description | Required | +| :--- | :--- | :--- | +| `PATH` | No description available | Yes | -**Options** +## Options -| **Option** | **Description** | +| Option | Description | | :--- | :--- | | `--root` | The directory you want to download the artifact to | | `--type` | The type of artifact you are downloading | - - - diff --git a/models/ref/cli/wandb-artifact/wandb-artifact-ls.mdx b/models/ref/cli/wandb-artifact/wandb-artifact-ls.mdx index f30e692b6c..db750e0633 100644 --- a/models/ref/cli/wandb-artifact/wandb-artifact-ls.mdx +++ b/models/ref/cli/wandb-artifact/wandb-artifact-ls.mdx @@ -1,21 +1,23 @@ --- -title: "wandb artifact ls" +title: wandb artifact ls --- -**Usage** - -`wandb artifact ls [OPTIONS] PATH` - -**Summary** - List all artifacts in a wandb project +## Usage -**Options** +```bash +wandb ls PATH [OPTIONS] +``` -| **Option** | **Description** | -| :--- | :--- | -| `-t, --type` | The type of artifacts to list | +## Arguments +| Argument | Description | Required | +| :--- | :--- | :--- | +| `PATH` | No description available | Yes | +## Options +| Option | Description | +| :--- | :--- | +| `--type`, `-t` | The type of artifacts to list | diff --git a/models/ref/cli/wandb-artifact/wandb-artifact-put.mdx b/models/ref/cli/wandb-artifact/wandb-artifact-put.mdx index 100c92034f..e32a20339d 100644 --- a/models/ref/cli/wandb-artifact/wandb-artifact-put.mdx +++ b/models/ref/cli/wandb-artifact/wandb-artifact-put.mdx @@ -1,28 +1,30 @@ --- -title: "wandb artifact put" +title: wandb artifact put --- -**Usage** +Upload an artifact to wandb -`wandb artifact put [OPTIONS] PATH` +## Usage -**Summary** +```bash +wandb put PATH [OPTIONS] +``` -Upload an artifact to wandb +## Arguments +| Argument | Description | Required | +| :--- | :--- | :--- | +| `PATH` | No description available | Yes | -**Options** +## Options -| **Option** | **Description** | +| Option | Description | | :--- | :--- | -| `-n, --name` | The name of the artifact to push: project/artifact_name | -| `-d, --description` | A description of this artifact | -| `-t, --type` | The type of the artifact | -| `-a, --alias` | An alias to apply to this artifact | +| `--name`, `-n` | The name of the artifact to push: project/artifact_name | +| `--description`, `-d` | A description of this artifact | +| `--type`, `-t` | The type of the artifact (default: dataset) | +| `--alias`, `-a` | An alias to apply to this artifact (default: ['latest']) | | `--id` | The run you want to upload to. | -| `--resume` | Resume the last run from your current directory. | -| `--skip_cache` | Skip caching while uploading artifact files. | -| `--policy [mutable|immutable]` | Set the storage policy while uploading artifact files. | - - - +| `--resume` | Resume the last run from your current directory. | +| `--skip_cache` | Skip caching while uploading artifact files. (default: False) | +| `--policy` | Set the storage policy while uploading artifact files. (default: mutable) | diff --git a/models/ref/cli/wandb-beta.mdx b/models/ref/cli/wandb-beta.mdx index 7cc89653cd..de0e3f1aec 100644 --- a/models/ref/cli/wandb-beta.mdx +++ b/models/ref/cli/wandb-beta.mdx @@ -1,25 +1,20 @@ ---- -title: wandb beta ---- - -**Usage** - -`wandb beta [OPTIONS] COMMAND [ARGS]...` - -**Summary** - -Beta versions of wandb CLI commands. Requires wandb-core. - - -**Options** - -| **Option** | **Description** | -| :--- | :--- | - - -**Commands** - -| **Command** | **Description** | -| :--- | :--- | -| sync | Upload .wandb files specified by PATHS. | - +--- +title: wandb beta +--- + +Beta versions of wandb CLI commands. + +These commands may change or even completely break in any release of wandb. + +## Usage + +```bash +wandb beta COMMAND [ARGS]... +``` + +## Commands + +| Command | Description | +| :--- | :--- | +| [leet](/models/ref/cli/wandb-beta/wandb-beta-leet) | Launch W&B LEET: the Lightweight Experiment Exploration Tool. | +| [sync](/models/ref/cli/wandb-beta/wandb-beta-sync) | Upload .wandb files specified by PATHS. | diff --git a/models/ref/cli/wandb-beta/wandb-beta-sync.mdx b/models/ref/cli/wandb-beta/wandb-beta-sync.mdx index c1c7aa4aac..755b48678e 100644 --- a/models/ref/cli/wandb-beta/wandb-beta-sync.mdx +++ b/models/ref/cli/wandb-beta/wandb-beta-sync.mdx @@ -1,33 +1,42 @@ --- -title: "wandb beta sync" +title: wandb beta sync --- -**Usage** - -`wandb beta sync [OPTIONS] WANDB_DIR` - -**Summary** - Upload .wandb files specified by PATHS. -PATHS can include .wandb files, run directories containing .wandb files, and -"wandb" directories containing run directories. +This is a beta re-implementation of `wandb sync`. It is not feature complete, not guaranteed to work, and may change in backward-incompatible ways in any release of wandb. + +PATHS can include .wandb files, run directories containing .wandb files, and "wandb" directories containing run directories. For example, to sync all runs in a directory: + wandb beta sync ./wandb + To sync a specific run: + wandb beta sync ./wandb/run-20250813_124246-n67z9ude + Or equivalently: + wandb beta sync ./wandb/run-20250813_124246-n67z9ude/run-n67z9ude.wandb -**Options** +## Usage -| **Option** | **Description** | -| :--- | :--- | -| `--skip-synced / --no-skip-synced` | Skip runs that have already been synced with this command. | -| `--dry-run` | Print what would happen without uploading anything. | -| `-v, --verbose` | Print more information. | -| `-n` | Max number of runs to sync at a time. | +```bash +wandb sync [PATHS] [OPTIONS] +``` + +## Arguments +| Argument | Description | Required | +| :--- | :--- | :--- | +| `PATHS` | No description available | No | +## Options +| Option | Description | +| :--- | :--- | +| `--skip-synced` | Skip runs that have already been synced with this command. (default: True) | +| `--dry-run` | Print what would happen without uploading anything. (default: False) | +| `-v`, `--verbose` | Print more information. (default: False) | +| `-n` | Max number of runs to sync at a time. (default: 5) | diff --git a/models/ref/cli/wandb-controller.mdx b/models/ref/cli/wandb-controller.mdx index b8a493a422..392209c270 100644 --- a/models/ref/cli/wandb-controller.mdx +++ b/models/ref/cli/wandb-controller.mdx @@ -1,21 +1,23 @@ --- -title: "wandb controller" +title: wandb controller --- -**Usage** - -`wandb controller [OPTIONS] SWEEP_ID` - -**Summary** - Run the W&B local sweep controller +## Usage -**Options** +```bash +wandb controller SWEEP_ID [OPTIONS] +``` -| **Option** | **Description** | -| :--- | :--- | -| `--verbose` | Display verbose output | +## Arguments +| Argument | Description | Required | +| :--- | :--- | :--- | +| `SWEEP_ID` | No description available | Yes | +## Options +| Option | Description | +| :--- | :--- | +| `--verbose` | Display verbose output (default: False) | diff --git a/models/ref/cli/wandb-disabled.mdx b/models/ref/cli/wandb-disabled.mdx index 98b2a8c5db..3b18e141f9 100644 --- a/models/ref/cli/wandb-disabled.mdx +++ b/models/ref/cli/wandb-disabled.mdx @@ -1,21 +1,17 @@ --- -title: "wandb disabled" +title: wandb disabled --- -**Usage** - -`wandb disabled [OPTIONS]` - -**Summary** - Disable W&B. +## Usage -**Options** - -| **Option** | **Description** | -| :--- | :--- | -| `--service` | Disable W&B service [default: True] | - +```bash +wandb disabled [OPTIONS] +``` +## Options +| Option | Description | +| :--- | :--- | +| `--service` | Disable W&B service (default: True) | diff --git a/models/ref/cli/wandb-docker-run.mdx b/models/ref/cli/wandb-docker-run.mdx index 8f589ff4eb..d50c281204 100644 --- a/models/ref/cli/wandb-docker-run.mdx +++ b/models/ref/cli/wandb-docker-run.mdx @@ -1,26 +1,21 @@ --- -title: "wandb docker-run" +title: wandb docker-run --- -**Usage** +Wrap `docker run` and adds WANDB_API_KEY and WANDB_DOCKER environment variables. -`wandb docker-run [OPTIONS] [DOCKER_RUN_ARGS]...` - -**Summary** - -Wrap `docker run` and adds WANDB_API_KEY and WANDB_DOCKER environment -variables. - -This will also set the runtime to nvidia if the nvidia-docker executable is -present on the system and --runtime wasn't set. +This will also set the runtime to nvidia if the nvidia-docker executable is present on the system and --runtime wasn't set. See `docker run --help` for more details. +## Usage -**Options** - -| **Option** | **Description** | -| :--- | :--- | - +```bash +wandb docker-run [DOCKER_RUN_ARGS] +``` +## Arguments +| Argument | Description | Required | +| :--- | :--- | :--- | +| `DOCKER_RUN_ARGS` | No description available | No | diff --git a/models/ref/cli/wandb-docker.mdx b/models/ref/cli/wandb-docker.mdx index 4739ef131a..6518a1c7f8 100644 --- a/models/ref/cli/wandb-docker.mdx +++ b/models/ref/cli/wandb-docker.mdx @@ -1,48 +1,38 @@ --- -title: "wandb docker" +title: wandb docker --- -**Usage** +Run your code in a docker container. -`wandb docker [OPTIONS] [DOCKER_RUN_ARGS]... [DOCKER_IMAGE]` +W&B docker lets you run your code in a docker image ensuring wandb is configured. It adds the WANDB_DOCKER and WANDB_API_KEY environment variables to your container and mounts the current directory in /app by default. You can pass additional args which will be added to `docker run` before the image name is declared, we'll choose a default image for you if one isn't passed: -**Summary** +```sh wandb docker -v /mnt/dataset:/app/data wandb docker gcr.io/kubeflow-images-public/tensorflow-1.12.0-notebook-cpu:v0.4.0 --jupyter wandb docker wandb/deepo:keras-gpu --no-tty --cmd "python train.py --epochs=5" ``` -Run your code in a docker container. +By default, we override the entrypoint to check for the existence of wandb and install it if not present. If you pass the --jupyter flag we will ensure jupyter is installed and start jupyter lab on port 8888. If we detect nvidia-docker on your system we will use the nvidia runtime. If you just want wandb to set environment variable to an existing docker run command, see the wandb docker-run command. -W&B docker lets you run your code in a docker image ensuring wandb is -configured. It adds the WANDB_DOCKER and WANDB_API_KEY environment variables -to your container and mounts the current directory in /app by default. You -can pass additional args which will be added to `docker run` before the -image name is declared, we'll choose a default image for you if one isn't -passed: +## Usage - wandb docker -v /mnt/dataset:/app/data - wandb docker gcr.io/kubeflow-images-public/tensorflow-1.12.0-notebook-cpu:v0.4.0 --jupyter - wandb docker - wandb/deepo:keras-gpu --no-tty --cmd "python train.py --epochs=5" +```bash +wandb docker [DOCKER_RUN_ARGS] [DOCKER_IMAGE] [OPTIONS] +``` -By default, we override the entrypoint to check for the existence of wandb -and install it if not present. If you pass the --jupyter flag we will -ensure jupyter is installed and start jupyter lab on port 8888. If we -detect nvidia-docker on your system we will use the nvidia runtime. If you -just want wandb to set environment variable to an existing docker run -command, see the wandb docker-run command. +## Arguments +| Argument | Description | Required | +| :--- | :--- | :--- | +| `DOCKER_RUN_ARGS` | No description available | No | +| `DOCKER_IMAGE` | No description available | No | -**Options** +## Options -| **Option** | **Description** | +| Option | Description | | :--- | :--- | -| `--nvidia / --no-nvidia` | Use the nvidia runtime, defaults to nvidia if nvidia-docker is present | -| `--digest` | Output the image digest and exit | -| `--jupyter / --no-jupyter` | Run jupyter lab in the container | -| `--dir` | Which directory to mount the code in the container | -| `--no-dir` | Don't mount the current directory | -| `--shell` | The shell to start the container with | -| `--port` | The host port to bind jupyter on | +| `--nvidia` | Use the nvidia runtime, defaults to nvidia if nvidia-docker is present (default: False) | +| `--digest` | Output the image digest and exit (default: False) | +| `--jupyter` | Run jupyter lab in the container (default: False) | +| `--dir` | Which directory to mount the code in the container (default: /app) | +| `--no-dir` | Don't mount the current directory (default: False) | +| `--shell` | The shell to start the container with (default: /bin/bash) | +| `--port` | The host port to bind jupyter on (default: 8888) | | `--cmd` | The command to run in the container | -| `--no-tty` | Run the command without a tty | - - - +| `--no-tty` | Run the command without a tty (default: False) | diff --git a/models/ref/cli/wandb-enabled.mdx b/models/ref/cli/wandb-enabled.mdx index 8f5707901d..f818c1707d 100644 --- a/models/ref/cli/wandb-enabled.mdx +++ b/models/ref/cli/wandb-enabled.mdx @@ -1,21 +1,17 @@ --- -title: "wandb enabled" +title: wandb enabled --- -**Usage** - -`wandb enabled [OPTIONS]` - -**Summary** - Enable W&B. +## Usage -**Options** - -| **Option** | **Description** | -| :--- | :--- | -| `--service` | Enable W&B service [default: True] | - +```bash +wandb enabled [OPTIONS] +``` +## Options +| Option | Description | +| :--- | :--- | +| `--service` | Enable W&B service (default: True) | diff --git a/models/ref/cli/wandb-init.mdx b/models/ref/cli/wandb-init.mdx index 14b240e6c3..b11d024165 100644 --- a/models/ref/cli/wandb-init.mdx +++ b/models/ref/cli/wandb-init.mdx @@ -1,24 +1,20 @@ --- -title: "wandb init" +title: wandb init --- -**Usage** - -`wandb init [OPTIONS]` - -**Summary** - Configure a directory with Weights & Biases +## Usage -**Options** - -| **Option** | **Description** | -| :--- | :--- | -| `-p, --project` | The project to use. | -| `-e, --entity` | The entity to scope the project to. | -| `--reset` | Reset settings | -| `-m, --mode` | Can be "online", "offline" or "disabled". Defaults to online. | - +```bash +wandb init [OPTIONS] +``` +## Options +| Option | Description | +| :--- | :--- | +| `--project`, `-p` | The project to use. | +| `--entity`, `-e` | The entity to scope the project to. | +| `--reset` | Reset settings (default: False) | +| `--mode`, `-m` | Can be "online", "offline" or "disabled". Defaults to online. | diff --git a/models/ref/cli/wandb-job.mdx b/models/ref/cli/wandb-job.mdx index c826944c48..3946359a6c 100644 --- a/models/ref/cli/wandb-job.mdx +++ b/models/ref/cli/wandb-job.mdx @@ -1,27 +1,19 @@ ---- -title: wandb job ---- - -**Usage** - -`wandb job [OPTIONS] COMMAND [ARGS]...` - -**Summary** - -Commands for managing and viewing W&B jobs - - -**Options** - -| **Option** | **Description** | -| :--- | :--- | - - -**Commands** - -| **Command** | **Description** | -| :--- | :--- | -| create | Create a job from a source, without a wandb run. | -| describe | Describe a launch job. | -| list | List jobs in a project | - +--- +title: wandb job +--- + +Commands for managing and viewing W&B jobs + +## Usage + +```bash +wandb job COMMAND [ARGS]... +``` + +## Commands + +| Command | Description | +| :--- | :--- | +| [create](/models/ref/cli/wandb-job/wandb-job-create) | Create a job from a source, without a wandb run. | +| [describe](/models/ref/cli/wandb-job/wandb-job-describe) | Describe a launch job. | +| [list](/models/ref/cli/wandb-job/wandb-job-list) | List jobs in a project | diff --git a/models/ref/cli/wandb-job/wandb-job-create.mdx b/models/ref/cli/wandb-job/wandb-job-create.mdx index eb0a090718..6683591a05 100644 --- a/models/ref/cli/wandb-job/wandb-job-create.mdx +++ b/models/ref/cli/wandb-job/wandb-job-create.mdx @@ -1,37 +1,40 @@ --- -title: "wandb job create" +title: wandb job create --- -**Usage** - -`wandb job create [OPTIONS] {git|code|image} PATH` - -**Summary** - Create a job from a source, without a wandb run. Jobs can be of three types, git, code, or image. -git: A git source, with an entrypoint either in the path or provided -explicitly pointing to the main python executable. code: A code path, -containing a requirements.txt file. image: A docker image. +git: A git source, with an entrypoint either in the path or provided explicitly pointing to the main python executable. code: A code path, containing a requirements.txt file. image: A docker image. +## Usage -**Options** +```bash +wandb create JOB_TYPE PATH [OPTIONS] +``` -| **Option** | **Description** | -| :--- | :--- | -| `-p, --project` | The project you want to list jobs from. | -| `-e, --entity` | The entity the jobs belong to | -| `-n, --name` | Name for the job | -| `-d, --description` | Description for the job | -| `-a, --alias` | Alias for the job | -| `--entry-point` | Entrypoint to the script, including an executable and an entrypoint file. Required for code or repo jobs. If --build-context is provided, paths in the entrypoint command will be relative to the build context. | -| `-g, --git-hash` | Commit reference to use as the source for git jobs | -| `-r, --runtime` | Python runtime to execute the job | -| `-b, --build-context` | Path to the build context from the root of the job source code. If provided, this is used as the base path for the Dockerfile and entrypoint. | -| `--base-image` | Base image to use for the job. Incompatible with image jobs. | -| `--dockerfile` | Path to the Dockerfile for the job. If --build- context is provided, the Dockerfile path will be relative to the build context. | +## Arguments +| Argument | Description | Required | +| :--- | :--- | :--- | +| `JOB_TYPE` | No description available | Yes | +| `PATH` | No description available | Yes | +## Options +| Option | Description | +| :--- | :--- | +| `--project`, `-p` | The project you want to list jobs from. | +| `--entity`, `-e` | The entity the jobs belong to | +| `--name`, `-n` | Name for the job | +| `--description`, `-d` | Description for the job | +| `--alias`, `-a` | Alias for the job | +| `--entry-point`, `-E` | Entrypoint to the script, including an executable and an entrypoint file. Required for code or repo jobs. If --build-context is provided, paths in the entrypoint command will be relative to the build context. | +| `--git-hash`, `-g` | Commit reference to use as the source for git jobs | +| `--runtime`, `-r` | Python runtime to execute the job | +| `--build-context`, `-b` | Path to the build context from the root of the job source code. If provided, this is used as the base path for the Dockerfile and entrypoint. | +| `--base-image`, `-B` | Base image to use for the job. Incompatible with image jobs. | +| `--dockerfile`, `-D` | Path to the Dockerfile for the job. If --build-context is provided, the Dockerfile path will be relative to the build context. | +| `--service`, `-s` | Service configurations in format serviceName=policy. Valid policies: always, never | +| `--schema` | Path to the schema file for the job. | diff --git a/models/ref/cli/wandb-job/wandb-job-describe.mdx b/models/ref/cli/wandb-job/wandb-job-describe.mdx index 9e58d0f962..47186f59a1 100644 --- a/models/ref/cli/wandb-job/wandb-job-describe.mdx +++ b/models/ref/cli/wandb-job/wandb-job-describe.mdx @@ -1,21 +1,17 @@ --- -title: "wandb job describe" +title: wandb job describe --- -**Usage** +Describe a launch job. Provide the launch job in the form of: entity/project/job-name:alias-or-version -`wandb job describe [OPTIONS] JOB` - -**Summary** - -Describe a launch job. Provide the launch job in the form of: -entity/project/job-name:alias-or-version - - -**Options** - -| **Option** | **Description** | -| :--- | :--- | +## Usage +```bash +wandb describe JOB +``` +## Arguments +| Argument | Description | Required | +| :--- | :--- | :--- | +| `JOB` | No description available | Yes | diff --git a/models/ref/cli/wandb-job/wandb-job-list.mdx b/models/ref/cli/wandb-job/wandb-job-list.mdx index 0f27f7538a..92ad5518e0 100644 --- a/models/ref/cli/wandb-job/wandb-job-list.mdx +++ b/models/ref/cli/wandb-job/wandb-job-list.mdx @@ -1,22 +1,18 @@ --- -title: "wandb job list" +title: wandb job list --- -**Usage** - -`wandb job list [OPTIONS]` - -**Summary** - List jobs in a project +## Usage -**Options** - -| **Option** | **Description** | -| :--- | :--- | -| `-p, --project` | The project you want to list jobs from. | -| `-e, --entity` | The entity the jobs belong to | - +```bash +wandb list [OPTIONS] +``` +## Options +| Option | Description | +| :--- | :--- | +| `--project`, `-p` | The project you want to list jobs from. | +| `--entity`, `-e` | The entity the jobs belong to (default: models) | diff --git a/models/ref/cli/wandb-launch-agent.mdx b/models/ref/cli/wandb-launch-agent.mdx index f238549f74..cac769e80b 100644 --- a/models/ref/cli/wandb-launch-agent.mdx +++ b/models/ref/cli/wandb-launch-agent.mdx @@ -1,26 +1,23 @@ --- -title: "wandb launch-agent" +title: wandb launch-agent --- -**Usage** - -`wandb launch-agent [OPTIONS]` - -**Summary** - Run a W&B launch agent. +## Usage -**Options** - -| **Option** | **Description** | -| :--- | :--- | -| `-q, --queue` | The name of a queue for the agent to watch. Multiple -q flags supported. | -| `-e, --entity` | The entity to use. Defaults to current logged-in user | -| `-l, --log-file` | Destination for internal agent logs. Use - for stdout. By default all agents logs will go to debug.log in your wandb/ subdirectory or WANDB_DIR if set. | -| `-j, --max-jobs` | The maximum number of launch jobs this agent can run in parallel. Defaults to 1. Set to -1 for no upper limit | -| `-c, --config` | path to the agent config yaml to use | -| `-v, --verbose` | Display verbose output | - +```bash +wandb launch-agent [OPTIONS] +``` +## Options +| Option | Description | +| :--- | :--- | +| `--queue`, `-q` | The name of a queue for the agent to watch. Multiple -q flags supported. | +| `--entity`, `-e` | The entity to use. Defaults to current logged-in user | +| `--log-file`, `-l` | Destination for internal agent logs. Use - for stdout. By default all agents logs will go to debug.log in your wandb/ subdirectory or WANDB_DIR if set. | +| `--max-jobs`, `-j` | The maximum number of launch jobs this agent can run in parallel. Defaults to 1. Set to -1 for no upper limit | +| `--config`, `-c` | path to the agent config yaml to use | +| `--url`, `-u` | a wandb client registration URL, this is generated in the UI | +| `--verbose`, `-v` | Display verbose output (default: 0) | diff --git a/models/ref/cli/wandb-launch-sweep.mdx b/models/ref/cli/wandb-launch-sweep.mdx index 3f42c2ecea..f032778acc 100644 --- a/models/ref/cli/wandb-launch-sweep.mdx +++ b/models/ref/cli/wandb-launch-sweep.mdx @@ -1,25 +1,27 @@ --- -title: "wandb launch-sweep" +title: wandb launch-sweep --- -**Usage** - -`wandb launch-sweep [OPTIONS] [CONFIG]` - -**Summary** - Run a W&B launch sweep (Experimental). +## Usage -**Options** +```bash +wandb launch-sweep [CONFIG] [OPTIONS] +``` -| **Option** | **Description** | -| :--- | :--- | -| `-q, --queue` | The name of a queue to push the sweep to | -| `-p, --project` | Name of the project which the agent will watch. If passed in, will override the project value passed in using a config file | -| `-e, --entity` | The entity to use. Defaults to current logged-in user | -| `-r, --resume_id` | Resume a launch sweep by passing an 8-char sweep id. Queue required | -| `--prior_run` | ID of an existing run to add to this sweep | +## Arguments +| Argument | Description | Required | +| :--- | :--- | :--- | +| `CONFIG` | No description available | No | +## Options +| Option | Description | +| :--- | :--- | +| `--queue`, `-q` | The name of a queue to push the sweep to | +| `--project`, `-p` | Name of the project which the agent will watch. If passed in, will override the project value passed in using a config file | +| `--entity`, `-e` | The entity to use. Defaults to current logged-in user | +| `--resume_id`, `-r` | Resume a launch sweep by passing an 8-char sweep id. Queue required | +| `--prior_run`, `-R` | ID of an existing run to add to this sweep | diff --git a/models/ref/cli/wandb-launch.mdx b/models/ref/cli/wandb-launch.mdx index 1122a58946..4a4d2aed6d 100644 --- a/models/ref/cli/wandb-launch.mdx +++ b/models/ref/cli/wandb-launch.mdx @@ -1,37 +1,38 @@ --- -title: "wandb launch" +title: wandb launch --- -**Usage** - -`wandb launch [OPTIONS]` - -**Summary** - Launch or queue a W&B Job. See https://wandb.me/launch +## Usage -**Options** - -| **Option** | **Description** | -| :--- | :--- | -| `-u, --uri (str)` | Local path or git repo uri to launch. If provided this command will create a job from the specified uri. | -| `-j, --job (str)` | Name of the job to launch. If passed in, launch does not require a uri. | -| `--entry-point` | Entry point within project. [default: main]. If the entry point is not found, attempts to run the project file with the specified name as a script, using 'python' to run .py files and the default shell (specified by environment variable $SHELL) to run .sh files. If passed in, will override the entrypoint value passed in using a config file. | -| `--build-context (str)` | Path to the build context within the source code. Defaults to the root of the source code. Compatible only with -u. | -| `--name` | Name of the run under which to launch the run. If not specified, a random run name will be used to launch run. If passed in, will override the name passed in using a config file. | -| `-e, --entity (str)` | Name of the target entity which the new run will be sent to. Defaults to using the entity set by local wandb/settings folder. If passed in, will override the entity value passed in using a config file. | -| `-p, --project (str)` | Name of the target project which the new run will be sent to. Defaults to using the project name given by the source uri or for github runs, the git repo name. If passed in, will override the project value passed in using a config file. | -| `-r, --resource` | Execution resource to use for run. Supported values: 'local-process', 'local-container', 'kubernetes', 'sagemaker', 'gcp-vertex'. This is now a required parameter if pushing to a queue with no resource configuration. If passed in, will override the resource value passed in using a config file. | -| `-d, --docker-image` | Specific docker image you'd like to use. In the form name:tag. If passed in, will override the docker image value passed in using a config file. | -| `--base-image` | Docker image to run job code in. Incompatible with --docker-image. | -| `-c, --config` | Path to JSON file (must end in '.json') or JSON string which will be passed as a launch config. Dictation how the launched run will be configured. | -| `-v, --set-var` | Set template variable values for queues with allow listing enabled, as key-value pairs e.g. `--set-var key1=value1 --set-var key2=value2` | -| `-q, --queue` | Name of run queue to push to. If none, launches single run directly. If supplied without an argument (`--queue`), defaults to queue 'default'. Else, if name supplied, specified run queue must exist under the project and entity supplied. | -| `--async` | Flag to run the job asynchronously. Defaults to false, i.e. unless --async is set, wandb launch will wait for the job to finish. This option is incompatible with --queue; asynchronous options when running with an agent should be set on wandb launch-agent. | -| `--resource-args` | Path to JSON file (must end in '.json') or JSON string which will be passed as resource args to the compute resource. The exact content which should be provided is different for each execution backend. See documentation for layout of this file. | -| `--dockerfile` | Path to the Dockerfile used to build the job, relative to the job's root | -| `--priority [critical|high|medium|low]` | When --queue is passed, set the priority of the job. Launch jobs with higher priority are served first. The order, from highest to lowest priority, is: critical, high, medium, low | - +```bash +wandb launch [OPTIONS] +``` +## Options +| Option | Description | +| :--- | :--- | +| `--uri`, `-u` | Local path or git repo uri to launch. If provided this command will create a job from the specified uri. | +| `--job`, `-j` | Name of the job to launch. If passed in, launch does not require a uri. | +| `--entry-point`, `-E` | Entry point within project. [default: main]. If the entry point is not found, attempts to run the project file with the specified name as a script, using 'python' to run .py files and the default shell (specified by environment variable $SHELL) to run .sh files. If passed in, will override the entrypoint value passed in using a config file. | +| `--git-version`, `-g` | Version of the project to run, as a Git commit reference for Git projects. | +| `--build-context` | Path to the build context within the source code. Defaults to the root of the source code. Compatible only with -u. | +| `--job-name`, `-J` | Name for the job created if the -u,--uri flag is passed in. | +| `--name` | Name of the run under which to launch the run. If not specified, a random run name will be used to launch run. If passed in, will override the name passed in using a config file. | +| `--entity`, `-e` | Name of the target entity which the new run will be sent to. Defaults to using the entity set by local wandb/settings folder. If passed in, will override the entity value passed in using a config file. | +| `--project`, `-p` | Name of the target project which the new run will be sent to. Defaults to using the project name given by the source uri or for github runs, the git repo name. If passed in, will override the project value passed in using a config file. | +| `--resource`, `-r` | Execution resource to use for run. Supported values: 'local-process', 'local-container', 'kubernetes', 'sagemaker', 'gcp-vertex'. This is now a required parameter if pushing to a queue with no resource configuration. If passed in, will override the resource value passed in using a config file. | +| `--docker-image`, `-d` | Specific docker image you'd like to use. In the form name:tag. If passed in, will override the docker image value passed in using a config file. | +| `--base-image`, `-B` | Docker image to run job code in. Incompatible with --docker-image. | +| `--config`, `-c` | Path to JSON file (must end in '.json') or JSON string which will be passed as a launch config. Dictation how the launched run will be configured. | +| `--set-var`, `-v` | Set template variable values for queues with allow listing enabled, as key-value pairs e.g. `--set-var key1=value1 --set-var key2=value2` | +| `--queue`, `-q` | Name of run queue to push to. If none, launches single run directly. If supplied without an argument (`--queue`), defaults to queue 'default'. Else, if name supplied, specified run queue must exist under the project and entity supplied. | +| `--async` | Flag to run the job asynchronously. Defaults to false, i.e. unless --async is set, wandb launch will wait for the job to finish. This option is incompatible with --queue; asynchronous options when running with an agent should be set on wandb launch-agent. (default: False) | +| `--resource-args`, `-R` | Path to JSON file (must end in '.json') or JSON string which will be passed as resource args to the compute resource. The exact content which should be provided is different for each execution backend. See documentation for layout of this file. | +| `--build`, `-b` | Flag to build an associated job and push to queue as an image job. (default: False) | +| `--repository`, `-rg` | Name of a remote repository. Will be used to push a built image to. | +| `--project-queue`, `-pq` | Name of the project containing the queue to push to. If none, defaults to entity level queues. | +| `--dockerfile`, `-D` | Path to the Dockerfile used to build the job, relative to the job's root | +| `--priority`, `-P` | When --queue is passed, set the priority of the job. Launch jobs with higher priority are served first. The order, from highest to lowest priority, is: critical, high, medium, low | diff --git a/models/ref/cli/wandb-login.mdx b/models/ref/cli/wandb-login.mdx index 9ad26ebc32..53c6c8e391 100644 --- a/models/ref/cli/wandb-login.mdx +++ b/models/ref/cli/wandb-login.mdx @@ -1,25 +1,31 @@ --- -title: "wandb login" +title: wandb login --- -**Usage** +Verify and store your API key for authentication with W&B services. -`wandb login [OPTIONS] [KEY]...` +By default, only store credentials locally without verifying them with W&B. To verify credentials, set `--verify=True`. -**Summary** +For server deployments (dedicated cloud or customer-managed instances), specify the host URL using the `--host` flag. You can also set environment variables `WANDB_BASE_URL` and `WANDB_API_KEY` instead of running the `login` command with host parameters. -Login to Weights & Biases +## Usage +```bash +wandb login [KEY] [OPTIONS] +``` -**Options** - -| **Option** | **Description** | -| :--- | :--- | -| `--cloud` | Login to the cloud instead of local | -| `--host, --base-url` | Login to a specific instance of W&B | -| `--relogin` | Force relogin if already logged in. | -| `--anonymously` | Log in anonymously | -| `--verify / --no-verify` | Verify login credentials | +## Arguments +| Argument | Description | Required | +| :--- | :--- | :--- | +| `KEY` | No description available | No | +## Options +| Option | Description | +| :--- | :--- | +| `--cloud` | Login to the cloud instead of local (default: False) | +| `--host`, `--base-url` | Login to a specific instance of W&B | +| `--relogin` | Force relogin if already logged in. | +| `--anonymously` | Log in anonymously (default: False) | +| `--verify` | Verify login credentials (default: False) | diff --git a/models/ref/cli/wandb-offline.mdx b/models/ref/cli/wandb-offline.mdx index f697b5c230..8ec0215f94 100644 --- a/models/ref/cli/wandb-offline.mdx +++ b/models/ref/cli/wandb-offline.mdx @@ -1,20 +1,13 @@ --- -title: "wandb offline" +title: wandb offline --- -**Usage** - -`wandb offline [OPTIONS]` - -**Summary** - -Disable W&B sync - - -**Options** - -| **Option** | **Description** | -| :--- | :--- | +Save data logged to W&B locally without uploading it to the cloud. +Use `wandb online` or `wandb sync` to upload offline runs. +## Usage +```bash +wandb offline +``` diff --git a/models/ref/cli/wandb-online.mdx b/models/ref/cli/wandb-online.mdx index 9dc2e6dab5..315cd1697a 100644 --- a/models/ref/cli/wandb-online.mdx +++ b/models/ref/cli/wandb-online.mdx @@ -1,20 +1,11 @@ --- -title: "wandb online" +title: wandb online --- -**Usage** - -`wandb online [OPTIONS]` - -**Summary** - -Enable W&B sync - - -**Options** - -| **Option** | **Description** | -| :--- | :--- | - +Undo `wandb offline`. +## Usage +```bash +wandb online +``` diff --git a/models/ref/cli/wandb-pull.mdx b/models/ref/cli/wandb-pull.mdx index 832ca57f81..19f7f9b1bc 100644 --- a/models/ref/cli/wandb-pull.mdx +++ b/models/ref/cli/wandb-pull.mdx @@ -1,22 +1,24 @@ --- -title: "wandb pull" +title: wandb pull --- -**Usage** - -`wandb pull [OPTIONS] RUN` - -**Summary** - Pull files from Weights & Biases +## Usage -**Options** +```bash +wandb pull RUN [OPTIONS] +``` -| **Option** | **Description** | -| :--- | :--- | -| `-p, --project` | The project you want to download. | -| `-e, --entity` | The entity to scope the listing to. | +## Arguments +| Argument | Description | Required | +| :--- | :--- | :--- | +| `RUN` | No description available | Yes | +## Options +| Option | Description | +| :--- | :--- | +| `--project`, `-p` | The project you want to download. | +| `--entity`, `-e` | The entity to scope the listing to. (default: models) | diff --git a/models/ref/cli/wandb-restore.mdx b/models/ref/cli/wandb-restore.mdx index 9f134867ec..875470e298 100644 --- a/models/ref/cli/wandb-restore.mdx +++ b/models/ref/cli/wandb-restore.mdx @@ -1,26 +1,26 @@ --- -title: "wandb restore" +title: wandb restore --- -**Usage** +Restore code, config and docker state for a run. Retrieves code from latest commit if code was not saved with `wandb.save()` or `wandb.init(save_code=True)`. -`wandb restore [OPTIONS] RUN` +## Usage -**Summary** +```bash +wandb restore RUN [OPTIONS] +``` -Restore code, config and docker state for a run. Retrieves code from latest -commit if code was not saved with `wandb.save()` or -`wandb.init(save_code=True)`. +## Arguments +| Argument | Description | Required | +| :--- | :--- | :--- | +| `RUN` | No description available | Yes | -**Options** +## Options -| **Option** | **Description** | +| Option | Description | | :--- | :--- | -| `--no-git` | Don't restore git state | -| `--branch / --no-branch` | Whether to create a branch or checkout detached | -| `-p, --project` | The project you wish to upload to. | -| `-e, --entity` | The entity to scope the listing to. | - - - +| `--no-git` | Don't restore git state (default: False) | +| `--branch` | Whether to create a branch or checkout detached (default: True) | +| `--project`, `-p` | The project you wish to upload to. | +| `--entity`, `-e` | The entity to scope the listing to. | diff --git a/models/ref/cli/wandb-scheduler.mdx b/models/ref/cli/wandb-scheduler.mdx index 26651cb7b8..c7b4cd84c6 100644 --- a/models/ref/cli/wandb-scheduler.mdx +++ b/models/ref/cli/wandb-scheduler.mdx @@ -1,20 +1,17 @@ --- -title: "wandb scheduler" +title: wandb scheduler --- -**Usage** - -`wandb scheduler [OPTIONS] SWEEP_ID` - -**Summary** - Run a W&B launch sweep scheduler (Experimental) +## Usage -**Options** - -| **Option** | **Description** | -| :--- | :--- | - +```bash +wandb scheduler SWEEP_ID +``` +## Arguments +| Argument | Description | Required | +| :--- | :--- | :--- | +| `SWEEP_ID` | No description available | Yes | diff --git a/models/ref/cli/wandb-server.mdx b/models/ref/cli/wandb-server.mdx index 729d63fcab..d9cd16086b 100644 --- a/models/ref/cli/wandb-server.mdx +++ b/models/ref/cli/wandb-server.mdx @@ -1,26 +1,18 @@ ---- -title: wandb server ---- - -**Usage** - -`wandb server [OPTIONS] COMMAND [ARGS]...` - -**Summary** - -Commands for operating a local W&B server - - -**Options** - -| **Option** | **Description** | -| :--- | :--- | - - -**Commands** - -| **Command** | **Description** | -| :--- | :--- | -| start | Start a local W&B server | -| stop | Stop a local W&B server | - +--- +title: wandb server +--- + +Commands for operating a local W&B server + +## Usage + +```bash +wandb server COMMAND [ARGS]... +``` + +## Commands + +| Command | Description | +| :--- | :--- | +| [start](/models/ref/cli/wandb-server/wandb-server-start) | Start a local W&B server | +| [stop](/models/ref/cli/wandb-server/wandb-server-stop) | Stop a local W&B server | diff --git a/models/ref/cli/wandb-server/wandb-server-start.mdx b/models/ref/cli/wandb-server/wandb-server-start.mdx index 9ca8debd55..be74c555c2 100644 --- a/models/ref/cli/wandb-server/wandb-server-start.mdx +++ b/models/ref/cli/wandb-server/wandb-server-start.mdx @@ -1,23 +1,21 @@ --- -title: "wandb server start" +title: wandb server start --- -**Usage** - -`wandb server start [OPTIONS]` - -**Summary** - Start a local W&B server +## Usage -**Options** - -| **Option** | **Description** | -| :--- | :--- | -| `-p, --port` | The host port to bind W&B server on | -| `-e, --env` | Env vars to pass to wandb/local | -| `--daemon / --no-daemon` | Run or don't run in daemon mode | - +```bash +wandb start [OPTIONS] +``` +## Options +| Option | Description | +| :--- | :--- | +| `--port`, `-p` | The host port to bind W&B server on (default: 8080) | +| `--env`, `-e` | Env vars to pass to wandb/local (default: []) | +| `--daemon` | Run or don't run in daemon mode (default: True) | +| `--upgrade` | Upgrade to the most recent version (default: False) | +| `--edge` | Run the bleeding edge (default: False) | diff --git a/models/ref/cli/wandb-server/wandb-server-stop.mdx b/models/ref/cli/wandb-server/wandb-server-stop.mdx index de51b2ad40..408e546dfc 100644 --- a/models/ref/cli/wandb-server/wandb-server-stop.mdx +++ b/models/ref/cli/wandb-server/wandb-server-stop.mdx @@ -1,20 +1,11 @@ --- -title: "wandb server stop" +title: wandb server stop --- -**Usage** - -`wandb server stop [OPTIONS]` - -**Summary** - Stop a local W&B server +## Usage -**Options** - -| **Option** | **Description** | -| :--- | :--- | - - - +```bash +wandb stop +``` diff --git a/models/ref/cli/wandb-status.mdx b/models/ref/cli/wandb-status.mdx index da447ca591..b0ed33d707 100644 --- a/models/ref/cli/wandb-status.mdx +++ b/models/ref/cli/wandb-status.mdx @@ -1,21 +1,17 @@ --- -title: "wandb status" +title: wandb status --- -**Usage** - -`wandb status [OPTIONS]` - -**Summary** - Show configuration settings +## Usage -**Options** - -| **Option** | **Description** | -| :--- | :--- | -| `--settings / --no-settings` | Show the current settings | - +```bash +wandb status [OPTIONS] +``` +## Options +| Option | Description | +| :--- | :--- | +| `--settings` | Show the current settings (default: True) | diff --git a/models/ref/cli/wandb-sweep.mdx b/models/ref/cli/wandb-sweep.mdx index 857b384d77..3ca1c6f140 100644 --- a/models/ref/cli/wandb-sweep.mdx +++ b/models/ref/cli/wandb-sweep.mdx @@ -1,33 +1,35 @@ --- -title: "wandb sweep" +title: wandb sweep --- -**Usage** +Initialize a hyperparameter sweep. Search for hyperparameters that optimizes a cost function of a machine learning model by testing various combinations. -`wandb sweep [OPTIONS] CONFIG_YAML_OR_SWEEP_ID` +## Usage -**Summary** +```bash +wandb sweep CONFIG_YAML_OR_SWEEP_ID [OPTIONS] +``` -Initialize a hyperparameter sweep. Search for hyperparameters that optimizes -a cost function of a machine learning model by testing various combinations. +## Arguments +| Argument | Description | Required | +| :--- | :--- | :--- | +| `CONFIG_YAML_OR_SWEEP_ID` | No description available | Yes | -**Options** +## Options -| **Option** | **Description** | +| Option | Description | | :--- | :--- | -| `-p, --project` | The name of the project where W&B runs created from the sweep are sent to. If the project is not specified, the run is sent to a project labeled Uncategorized. | -| `-e, --entity` | The username or team name where you want to send W&B runs created by the sweep to. Ensure that the entity you specify already exists. If you don't specify an entity, the run will be sent to your default entity, which is usually your username. | -| `--controller` | Run local controller | -| `--verbose` | Display verbose output | -| `--name` | The name of the sweep. The sweep ID is used if no name is specified. | +| `--project`, `-p` | The name of the project where W&B runs created from the sweep are sent to. If the project is not specified, the run is sent to a project labeled Uncategorized. | +| `--entity`, `-e` | The username or team name where you want to send W&B runs created by the sweep to. Ensure that the entity you specify already exists. If you don't specify an entity, the run will be sent to your default entity, which is usually your username. | +| `--controller` | Run local controller (default: False) | +| `--verbose` | Display verbose output (default: False) | +| `--name` | The name of the sweep. The sweep ID is used if no name is specified. | | `--program` | Set sweep program | +| `--settings` | Set sweep settings | | `--update` | Update pending sweep | -| `--stop` | Finish a sweep to stop running new runs and let currently running runs finish. | -| `--cancel` | Cancel a sweep to kill all running runs and stop running new runs. | -| `--pause` | Pause a sweep to temporarily stop running new runs. | -| `--resume` | Resume a sweep to continue running new runs. | -| `--prior_run` | ID of an existing run to add to this sweep | - - - +| `--stop` | Finish a sweep to stop running new runs and let currently running runs finish. (default: False) | +| `--cancel` | Cancel a sweep to kill all running runs and stop running new runs. (default: False) | +| `--pause` | Pause a sweep to temporarily stop running new runs. (default: False) | +| `--resume` | Resume a sweep to continue running new runs. (default: False) | +| `--prior_run`, `-R` | ID of an existing run to add to this sweep | diff --git a/models/ref/cli/wandb-sync.mdx b/models/ref/cli/wandb-sync.mdx index 22563e8713..74a5afb7dc 100644 --- a/models/ref/cli/wandb-sync.mdx +++ b/models/ref/cli/wandb-sync.mdx @@ -1,39 +1,54 @@ --- -title: "wandb sync" +title: wandb sync --- -**Usage** +Synchronize W&B run data to the cloud. -`wandb sync [OPTIONS] [PATH]...` +If PATH is provided, sync runs found at the given path. If a path is not specified, search for `./wandb` first, then search for a `wandb/` subdirectory. -**Summary** +To sync a specific run: -Upload an offline training directory to W&B +wandb sync ./wandb/run-20250813_124246-n67z9ude +Or equivalently: -**Options** +wandb sync ./wandb/run-20250813_124246-n67z9ude/run-n67z9ude.wandb -| **Option** | **Description** | +## Usage + +```bash +wandb sync [PATH] [OPTIONS] +``` + +## Arguments + +| Argument | Description | Required | +| :--- | :--- | :--- | +| `PATH` | No description available | No | + +## Options + +| Option | Description | | :--- | :--- | +| `--view` | View runs (default: False) | +| `--verbose` | Verbose (default: False) | | `--id` | The run you want to upload to. | -| `-p, --project` | The project you want to upload to. | -| `-e, --entity` | The entity to scope to. | -| `--job_type` | Specifies the type of run for grouping related runs together. | -| `--sync-tensorboard / --no-sync-tensorboard` | Stream tfevent files to wandb. | +| `--project`, `-p` | The project you want to upload to. | +| `--entity`, `-e` | The entity to scope to. | +| `--job_type` | Specifies the type of run for grouping related runs together. | +| `--sync-tensorboard` | Stream tfevent files to wandb. | | `--include-globs` | Comma separated list of globs to include. | | `--exclude-globs` | Comma separated list of globs to exclude. | -| `--include-online / --no-include-online` | Include online runs | -| `--include-offline / --no-include-offline` | Include offline runs | -| `--include-synced / --no-include-synced` | Include synced runs | -| `--mark-synced / --no-mark-synced` | Mark runs as synced | -| `--sync-all` | Sync all runs | -| `--clean` | Delete synced runs | -| `--clean-old-hours` | Delete runs created before this many hours. To be used alongside --clean flag. | -| `--clean-force` | Clean without confirmation prompt. | -| `--show` | Number of runs to show | -| `--append` | Append run | -| `--skip-console` | Skip console logs | -| `--replace-tags` | Replace tags in the format 'old_tag1=new_tag1,old_tag2=new_tag2' | - - - +| `--include-online` | Include online runs | +| `--include-offline` | Include offline runs | +| `--include-synced` | Include synced runs | +| `--mark-synced` | Mark runs as synced (default: True) | +| `--sync-all` | Sync all runs (default: False) | +| `--clean` | Delete synced runs (default: False) | +| `--clean-old-hours` | Delete runs created before this many hours. To be used alongside --clean flag. (default: 24) | +| `--clean-force` | Clean without confirmation prompt. (default: False) | +| `--ignore` | No description available | +| `--show` | Number of runs to show (default: 5) | +| `--append` | Append run (default: False) | +| `--skip-console` | Skip console logs (default: False) | +| `--replace-tags` | Replace tags in the format 'old_tag1=new_tag1,old_tag2=new_tag2' | diff --git a/models/ref/cli/wandb-verify.mdx b/models/ref/cli/wandb-verify.mdx index 355ca2f4d4..aba08176ce 100644 --- a/models/ref/cli/wandb-verify.mdx +++ b/models/ref/cli/wandb-verify.mdx @@ -1,49 +1,37 @@ --- -title: "wandb verify" +title: wandb verify --- -**Usage** - -`wandb verify [OPTIONS]` - -**Summary** - Checks and verifies local instance of W&B. W&B checks for: Checks that the host is not `api.wandb.ai` (host check). -Verifies if the user is logged in correctly using the provided API key -(login check). +Verifies if the user is logged in correctly using the provided API key (login check). Checks that requests are made over HTTPS (secure requests). -Validates the CORS (Cross-Origin Resource Sharing) configuration of the -object store (CORS configuration). +Validates the CORS (Cross-Origin Resource Sharing) configuration of the object store (CORS configuration). + +Logs metrics, saves, and downloads files to check if runs are correctly recorded and accessible (run check). -Logs metrics, saves, and downloads files to check if runs are correctly -recorded and accessible (run check). +Saves and downloads artifacts to verify that the artifact storage and retrieval system is working as expected (artifact check). -Saves and downloads artifacts to verify that the artifact storage and -retrieval system is working as expected (artifact check). +Tests the GraphQL endpoint by uploading a file to ensure it can handle signed URL uploads (GraphQL PUT check). -Tests the GraphQL endpoint by uploading a file to ensure it can handle -signed URL uploads (GraphQL PUT check). +Checks the ability to send large payloads through the proxy (large payload check). -Checks the ability to send large payloads through the proxy (large payload -check). +Verifies that the installed version of the W&B package is up-to-date and compatible with the server (W&B version check). -Verifies that the installed version of the W&B package is up-to-date and -compatible with the server (W&B version check). +Creates and executes a sweep to ensure that sweep functionality is working correctly (sweeps check). -Creates and executes a sweep to ensure that sweep functionality is working -correctly (sweeps check). +## Usage +```bash +wandb verify [OPTIONS] +``` -**Options** +## Options -| **Option** | **Description** | +| Option | Description | | :--- | :--- | | `--host` | Test a specific instance of W&B | - - -