From b99fa8fab624207469360cde924d967162c4a7a9 Mon Sep 17 00:00:00 2001 From: Michael Stahnke Date: Tue, 28 Oct 2025 13:51:46 -0700 Subject: [PATCH 01/14] chore: Add gnumake to Flox env --- .flox/env/manifest.lock | 133 ++++++++++++++++++++++++++++++++++++++++ .flox/env/manifest.toml | 1 + 2 files changed, 134 insertions(+) diff --git a/.flox/env/manifest.lock b/.flox/env/manifest.lock index d5c204ec..5e202422 100644 --- a/.flox/env/manifest.lock +++ b/.flox/env/manifest.lock @@ -18,6 +18,9 @@ "pkg-path": "findutils", "outputs": "all" }, + "gnumake": { + "pkg-path": "gnumake" + }, "gnused": { "pkg-path": "gnused", "outputs": "all" @@ -836,6 +839,136 @@ "group": "toplevel", "priority": 5 }, + { + "attr_path": "gnumake", + "broken": false, + "derivation": "/nix/store/pf71f0ja823aanl6073z3slrpz2hpxr1-gnumake-4.4.1.drv", + "description": "Tool to control the generation of non-source files from sources", + "install_id": "gnumake", + "license": "GPL-3.0-or-later", + "locked_url": "https://github.com/flox/nixpkgs?rev=8eaee110344796db060382e15d3af0a9fc396e0e", + "name": "gnumake-4.4.1", + "pname": "gnumake", + "rev": "8eaee110344796db060382e15d3af0a9fc396e0e", + "rev_count": 864002, + "rev_date": "2025-09-19T10:20:10Z", + "scrape_date": "2025-09-21T05:38:43.319343Z", + "stabilities": [ + "unstable" + ], + "unfree": false, + "version": "4.4.1", + "outputs_to_install": [ + "man", + "out" + ], + "outputs": { + "info": "/nix/store/cwx5agxi3ig3gmbk4c4dn7df2krzlddy-gnumake-4.4.1-info", + "man": "/nix/store/a4aay80xgirjm8hk1rd142qcd1kkfps8-gnumake-4.4.1-man", + "out": "/nix/store/sjxx5p05vzq7xam62h21cyzkbyb1amvd-gnumake-4.4.1" + }, + "system": "aarch64-darwin", + "group": "toplevel", + "priority": 5 + }, + { + "attr_path": "gnumake", + "broken": false, + "derivation": "/nix/store/876aq0p8d0z7sfyjdawn9mrdfnv7n458-gnumake-4.4.1.drv", + "description": "Tool to control the generation of non-source files from sources", + "install_id": "gnumake", + "license": "GPL-3.0-or-later", + "locked_url": "https://github.com/flox/nixpkgs?rev=8eaee110344796db060382e15d3af0a9fc396e0e", + "name": "gnumake-4.4.1", + "pname": "gnumake", + "rev": "8eaee110344796db060382e15d3af0a9fc396e0e", + "rev_count": 864002, + "rev_date": "2025-09-19T10:20:10Z", + "scrape_date": "2025-09-21T06:10:24.182468Z", + "stabilities": [ + "unstable" + ], + "unfree": false, + "version": "4.4.1", + "outputs_to_install": [ + "man", + "out" + ], + "outputs": { + "debug": "/nix/store/j8lcp5zjdq0l0ipvji7s13vdc53nzcki-gnumake-4.4.1-debug", + "info": "/nix/store/8922q241lh4qbxd2g7jxsnjnkfmgap3z-gnumake-4.4.1-info", + "man": "/nix/store/0a4l47b9sqc28ssi5hsq21ivs2hmbzcp-gnumake-4.4.1-man", + "out": "/nix/store/9cns3585v908dwbf5nfqqjghv955ndrq-gnumake-4.4.1" + }, + "system": "aarch64-linux", + "group": "toplevel", + "priority": 5 + }, + { + "attr_path": "gnumake", + "broken": false, + "derivation": "/nix/store/xrm5hvv49gd5v31937jmr0vc6m8a1v64-gnumake-4.4.1.drv", + "description": "Tool to control the generation of non-source files from sources", + "install_id": "gnumake", + "license": "GPL-3.0-or-later", + "locked_url": "https://github.com/flox/nixpkgs?rev=8eaee110344796db060382e15d3af0a9fc396e0e", + "name": "gnumake-4.4.1", + "pname": "gnumake", + "rev": "8eaee110344796db060382e15d3af0a9fc396e0e", + "rev_count": 864002, + "rev_date": "2025-09-19T10:20:10Z", + "scrape_date": "2025-09-21T06:39:00.878032Z", + "stabilities": [ + "unstable" + ], + "unfree": false, + "version": "4.4.1", + "outputs_to_install": [ + "man", + "out" + ], + "outputs": { + "info": "/nix/store/451pi5y9s89na99pxv6jjvqa44r08dha-gnumake-4.4.1-info", + "man": "/nix/store/g7nffhgbmv3r01199lhp0qz741kvnlvf-gnumake-4.4.1-man", + "out": "/nix/store/fy063r4nqi1w79bklqhiv7ny0xwdqjp3-gnumake-4.4.1" + }, + "system": "x86_64-darwin", + "group": "toplevel", + "priority": 5 + }, + { + "attr_path": "gnumake", + "broken": false, + "derivation": "/nix/store/riz7jd6hvqpxzxgyhj76ianh96sxhvz4-gnumake-4.4.1.drv", + "description": "Tool to control the generation of non-source files from sources", + "install_id": "gnumake", + "license": "GPL-3.0-or-later", + "locked_url": "https://github.com/flox/nixpkgs?rev=8eaee110344796db060382e15d3af0a9fc396e0e", + "name": "gnumake-4.4.1", + "pname": "gnumake", + "rev": "8eaee110344796db060382e15d3af0a9fc396e0e", + "rev_count": 864002, + "rev_date": "2025-09-19T10:20:10Z", + "scrape_date": "2025-09-21T07:10:55.800436Z", + "stabilities": [ + "unstable" + ], + "unfree": false, + "version": "4.4.1", + "outputs_to_install": [ + "man", + "out" + ], + "outputs": { + "debug": "/nix/store/7vrxj6zy7y4a83d2q9585sxmcnkfs9ml-gnumake-4.4.1-debug", + "info": "/nix/store/m0ijkc5j3wdawh302pns9b45v9n6nq64-gnumake-4.4.1-info", + "man": "/nix/store/ha44mgbdcrzgah0dnjd28ax4hrdkc4mm-gnumake-4.4.1-man", + "out": "/nix/store/ahxj2q2mrl9z2k77ahqsl9j4zxq1wf84-gnumake-4.4.1" + }, + "system": "x86_64-linux", + "group": "toplevel", + "priority": 5 + }, { "attr_path": "gnused", "broken": false, diff --git a/.flox/env/manifest.toml b/.flox/env/manifest.toml index 56b8828f..5b1048d9 100644 --- a/.flox/env/manifest.toml +++ b/.flox/env/manifest.toml @@ -23,6 +23,7 @@ markdownlint-cli2.pkg-path = "markdownlint-cli2" markdownlint-cli2.pkg-group = "lint" curl.pkg-path = "curl" curl.outputs = "all" +gnumake.pkg-path = "gnumake" [hook] on-activate = ''' From 602508250eabdf32b0fedcf6199ebfc4a0baadff Mon Sep 17 00:00:00 2001 From: Michael Stahnke Date: Tue, 28 Oct 2025 13:53:26 -0700 Subject: [PATCH 02/14] Generate llms.txt and doc-content.txt for AI tools This commit adds the generations of llms.txt (more robust than what was there) as well a single docs-content.txt that can be fed to an agent or answer engine to set context of how to work with Flox. This does add a Makefile (sorry) because I needed something to run multiple steps when building the documentaiton site. The README has been updated to explain Makefile usage (and it's completely optional). The tools directory is also new, with a small python file to generate the AI indexing files. The robots.txt that helps the crawlers know where to work is maintained in the flox/floxwebsite repo. --- .github/workflows/ci.yml | 1 + Makefile | 43 ++++ README.md | 38 ++++ tools/README.md | 31 +++ tools/generate_llms_txt.py | 399 +++++++++++++++++++++++++++++++++++++ tools/generate_llms_txt.sh | 19 ++ 6 files changed, 531 insertions(+) create mode 100644 Makefile create mode 100644 tools/README.md create mode 100755 tools/generate_llms_txt.py create mode 100755 tools/generate_llms_txt.sh diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8075be19..42a22a28 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -47,6 +47,7 @@ jobs: with: command: | mkdocs build + python3 tools/generate_llms_txt.py ./site mkdir -p ./public/docs cp -R ./site/* ./public/docs/ chmod -R +w ./public/docs diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..f034cd9c --- /dev/null +++ b/Makefile @@ -0,0 +1,43 @@ +# Flox Documentation Makefile + +.PHONY: help dev build clean install + +# Default target +help: + @echo "Available targets:" + @echo " dev - Start development server with live reload" + @echo " build - Build static site and generate AI files" + @echo " clean - Clean build artifacts" + @echo " install - Install dependencies" + @echo " help - Show this help message" + +# Development server with live reload +dev: + @echo "Starting development server..." + @echo "Site will be available at: http://127.0.0.1:8000" + @echo "Press Ctrl+C to stop" + mkdocs serve + +# Build static site and generate AI files +build: + @echo "Building static site..." + mkdocs build + @echo "Generating AI files..." + python3 tools/generate_llms_txt.py ./site + @echo "✅ Build complete! Site available in ./site/" + +# Clean build artifacts +clean: + @echo "Cleaning build artifacts..." + rm -rf site/ + rm -rf public/ + @echo "✅ Clean complete!" + +# Install dependencies (if needed) +install: + @echo "Installing dependencies..." + @if command -v poetry >/dev/null 2>&1; then \ + poetry install; \ + else \ + echo "Poetry not found. Please install dependencies manually."; \ + fi diff --git a/README.md b/README.md index da0ff4f3..afe93e62 100644 --- a/README.md +++ b/README.md @@ -4,17 +4,55 @@ Live at: [flox.dev/docs](https://flox.dev/docs). ## Usage +### Quick Start + +```bash +# Activate the Flox environment +$ flox activate +✅ You are now using the environment 'floxdocs'. + +# Start development server +λ (floxdocs) $ make dev +``` + +The documentation will be available at `http://127.0.0.1:8000` with live reload. + +### Available Commands + +```bash +make dev # Start development server with live reload +make build # Build static site and generate AI files +make clean # Clean build artifacts +make help # Show all available commands ``` + +### Flox Native Usage + +You can still use the original Flox services approach: + +```bash $ flox activate ✔ You are now using the environment 'floxdocs'. λ (floxdocs) $ flox services start mkdocs ✔ Service 'mkdocs' started. + ``` + Once mkdocs service started you can preview the documentation at `https://127.0.0.1:8000`. +## AI-Friendly Documentation + +This documentation site automatically generates AI-friendly files for different use cases: + +- **`llms.txt`** - Optimized for AI agents with critical rules, workflows, and organized sitemap +- **`docs-content.txt`** - Comprehensive content for answer engines and RAG systems + +These files are automatically generated during the build process and are available at: +- `https://flox.dev/docs/llms.txt` +- `https://flox.dev/docs/docs-content.txt` ## Guidelines diff --git a/tools/README.md b/tools/README.md new file mode 100644 index 00000000..6f687e1b --- /dev/null +++ b/tools/README.md @@ -0,0 +1,31 @@ +# Tools + +This directory contains build tools and utilities for the Flox documentation site. + +## Scripts + +### `generate_llms_txt.py` + +Generates AI-friendly documentation files from the built MkDocs site: + +- **`llms.txt`** - Agent-focused file with critical rules, workflows, and organized sitemap +- **`docs-content.txt`** - Answer engine file with comprehensive documentation content + +**Usage:** +```bash +python3 tools/generate_llms_txt.py +``` + +### `generate_llms_txt.sh` + +Convenience script for local development. Generates both AI files after a MkDocs build. + +**Usage:** +```bash +mkdocs build +./tools/generate_llms_txt.sh +``` + +## Integration + +These scripts are automatically run during CI builds in `.github/workflows/ci.yml` to ensure the AI files are always up-to-date with the documentation content. diff --git a/tools/generate_llms_txt.py b/tools/generate_llms_txt.py new file mode 100755 index 00000000..89c46e61 --- /dev/null +++ b/tools/generate_llms_txt.py @@ -0,0 +1,399 @@ +#!/usr/bin/env python3 +""" +Generate llms.txt from the built MkDocs site. +This script scans the built site directory and creates a comprehensive llms.txt file. +""" + +import os +import re +import sys +from pathlib import Path +from urllib.parse import unquote + + +def normalize_url(path: str, base_url: str = "https://flox.dev/docs") -> str: + """Convert file path to URL.""" + # Remove leading/trailing slashes + path = path.strip('/') + if not path or path == 'index.html': + return base_url + # Remove .html extension + path = path.replace('.html', '') + return f"{base_url}/{path}" + + +def extract_title_from_html(html_content: str) -> str: + """Extract page title from HTML content.""" + # Check if this is a redirect page + if 'Redirecting...' in html_content or 'redirect' in html_content.lower(): + return None # Signal this is a redirect page + + # Try to find the first h1 tag + h1_match = re.search(r']*>(.*?)', html_content, re.DOTALL) + if h1_match: + title = h1_match.group(1).strip() + # Remove markdown tags and clean up + title = re.sub(r'<[^>]+>', '', title) + return title + + # Fallback to title tag + title_match = re.search(r'(.*?)', html_content, re.DOTALL) + if title_match: + title = title_match.group(1).strip() + title = title.replace(' - Flox Docs', '').strip() + return title + + return "Untitled" + + +def extract_description_from_html(html_content: str) -> str: + """Extract meta description or first paragraph.""" + # Try to find meta description + desc_match = re.search(r']*>.*?]*>(.*?)

', html_content, re.DOTALL) + if para_match: + desc = para_match.group(1).strip() + # Remove HTML tags + desc = re.sub(r'<[^>]+>', '', desc) + # Limit length + if len(desc) > 200: + desc = desc[:200] + "..." + return desc + + return "" + + +def categorize_page(url: str, title: str) -> str: + """Categorize pages for better organization.""" + if '/concepts/' in url: + return 'concepts' + elif '/tutorials/' in url: + return 'tutorials' + elif '/man/' in url: + return 'manual' + elif '/languages/' in url: + return 'languages' + elif '/install-flox/' in url: + return 'installation' + elif '/customer/' in url: + return 'customer' + elif '/snippets/' in url: + return 'snippets' + elif url.endswith('/docs') or url.endswith('/docs/'): + return 'overview' + else: + return 'other' + + +def get_page_description(url: str, title: str) -> str: + """Get a helpful description for common pages.""" + descriptions = { + 'concepts/environments': 'Understanding Flox environments and how they work', + 'concepts/activation': 'How to activate and use Flox environments', + 'concepts/floxhub': 'Understanding FloxHub package registry and sharing', + 'concepts/generations': 'Environment snapshots and version management', + 'concepts/packages-and-catalog': 'Package management and the Flox catalog', + 'concepts/services': 'Running services within Flox environments', + 'concepts/composition': 'Combining and layering multiple environments', + 'concepts/builds': 'Building packages and environments', + 'concepts/publishing': 'Publishing packages to FloxHub', + 'tutorials/creating-environments': 'Step-by-step guide to create your first environment', + 'tutorials/sharing-environments': 'How to share environments with team members', + 'tutorials/customizing-environments': 'Customizing shell environment and behavior', + 'tutorials/build-and-publish': 'Building and publishing custom packages', + 'tutorials/ci-cd': 'Using Flox in continuous integration pipelines', + 'tutorials/composition': 'Reusing and combining developer environments', + 'tutorials/multi-arch-environments': 'Cross-platform environment design', + 'tutorials/cuda': 'Using CUDA with Flox environments', + 'tutorials/migrations/homebrew': 'Migrating from Homebrew to Flox', + 'tutorials/migrations/nvm': 'Migrating from Node Version Manager to Flox', + 'languages/python': 'Python development with Flox', + 'languages/nodejs': 'Node.js and JavaScript development', + 'languages/go': 'Go development with Flox', + 'languages/rust': 'Rust development with Flox', + 'languages/c': 'C/C++ development with Flox', + 'languages/jvm': 'Java and JVM development', + 'languages/ruby': 'Ruby development with Flox', + 'install-flox/install': 'Installation instructions for Flox', + 'install-flox/uninstall': 'How to uninstall Flox', + 'flox-5-minutes': 'Quick start guide to get up and running', + } + + # Extract the key part of the URL + key = url.replace('https://flox.dev/docs/', '').replace('/index', '') + return descriptions.get(key, '') + + +def get_site_structure(site_dir: Path) -> list: + """Get all pages from the built site.""" + pages = [] + html_files = list(site_dir.rglob('*.html')) + + for html_file in sorted(html_files): + # Skip generated JS/search files + if html_file.name in ['search.html', '404.html', 'sitemap.xml']: + continue + + rel_path = html_file.relative_to(site_dir) + url = normalize_url(str(rel_path)) + + try: + with open(html_file, 'r', encoding='utf-8') as f: + content = f.read() + + title = extract_title_from_html(content) + + # Skip redirect pages + if title is None: + continue + + description = extract_description_from_html(content) + + description = get_page_description(url, title) + category = categorize_page(url, title) + + pages.append({ + 'url': url, + 'title': title, + 'path': str(rel_path), + 'description': description, + 'category': category + }) + except Exception as e: + print(f"Error processing {html_file}: {e}", file=sys.stderr) + + return pages + + +def extract_page_content(html_content: str) -> str: + """Extract main content from HTML for answer engine.""" + # Remove script and style elements + content = re.sub(r']*>.*?', '', html_content, flags=re.DOTALL) + content = re.sub(r']*>.*?', '', content, flags=re.DOTALL) + + # Extract main content area + main_match = re.search(r']*>(.*?)', content, re.DOTALL) + if main_match: + content = main_match.group(1) + + # Remove unwanted elements + content = re.sub(r']*>.*?', '', content, flags=re.DOTALL) + content = re.sub(r']*>.*?', '', content, flags=re.DOTALL) + content = re.sub(r']*>.*?', '', content, flags=re.DOTALL) + + # Remove license/copyright text + content = re.sub(r'Permission is hereby granted.*?DEALINGS IN THE SOFTWARE\.', '', content, flags=re.DOTALL) + content = re.sub(r'Copyright.*?All rights reserved\.', '', content, flags=re.DOTALL) + content = re.sub(r'THE SOFTWARE IS PROVIDED.*?DEALINGS IN THE SOFTWARE\.', '', content, flags=re.DOTALL) + content = re.sub(r'-->.*?Have questions\?', '', content, flags=re.DOTALL) + + # Remove HTML tags but preserve structure + content = re.sub(r']*>(.*?)', r'\n\n#\1 \2\n', content) + content = re.sub(r']*>(.*?)

', r'\1\n\n', content) + content = re.sub(r']*>(.*?)', r'- \1\n', content) + content = re.sub(r']*>(.*?)', r'`\1`', content) + content = re.sub(r']*>]*>(.*?)', r'```\n\1\n```', content, flags=re.DOTALL) + content = re.sub(r'<[^>]+>', '', content) + + # Clean up whitespace and remove empty lines + content = re.sub(r'\n\s*\n\s*\n', '\n\n', content) + content = re.sub(r'^\s*\n', '', content, flags=re.MULTILINE) + content = content.strip() + + # Only return substantial content (more than 100 chars) + if len(content) < 100: + return "" + + return content + + +def generate_llms_txt(site_dir: Path, output_path: Path): + """Generate llms.txt file for agents.""" + pages = get_site_structure(site_dir) + + # Read existing llms.txt to get the header + existing_llms = Path('docs/llms.txt') + header = "" + if existing_llms.exists(): + with open(existing_llms, 'r') as f: + lines = f.readlines() + # Extract header (everything before the Sitemap section) + for i, line in enumerate(lines): + if line.startswith('## Sitemap'): + header = ''.join(lines[:i]) + break + header = ''.join(lines) + + # Add key terminology section + terminology = """ +## Key Terms +- **Environment**: A reproducible development environment with specific packages and configurations +- **Manifest**: A declarative configuration file (manifest.toml) defining an environment's packages and settings +- **Generation**: A snapshot of an environment at a specific point in time, allowing rollbacks +- **FloxHub**: The package registry and sharing platform for Flox environments +- **Activation**: Running commands within a Flox environment's context +- **Catalog**: The collection of available packages that can be installed +- **Services**: Long-running processes defined in the manifest that can be managed by Flox + +## Quick Reference +### Common Workflows +- **New Project**: `flox init -d .` → `flox install -d . ` → `flox activate -d . -- ` +- **Multi-environment Project**: `flox init -d backend` + `flox init -d frontend` +- **Sharing Environment**: `flox push` → `flox pull` on another machine +- **Package Management**: `flox search ` → `flox show ` → `flox install -d . ` +- **Service Management**: Define in manifest → `flox services start ` → `flox services status` + +""" + + # Group pages by category + categories = {} + for page in pages: + cat = page['category'] + if cat not in categories: + categories[cat] = [] + categories[cat].append(page) + + # Generate organized sitemap + sitemap = ["## Documentation Structure\n"] + + # Define category order and titles + category_order = [ + ('overview', 'Overview'), + ('installation', 'Installation'), + ('tutorials', 'Tutorials & Getting Started'), + ('concepts', 'Core Concepts'), + ('languages', 'Language-Specific Guides'), + ('manual', 'Command Reference'), + ('customer', 'Customer Resources'), + ('snippets', 'Code Snippets'), + ('other', 'Other') + ] + + for cat_key, cat_title in category_order: + if cat_key in categories: + sitemap.append(f"### {cat_title}\n") + for page in sorted(categories[cat_key], key=lambda x: x['title']): + if page['description']: + sitemap.append(f"- [{page['title']}]({page['url']}) - {page['description']}\n") + else: + sitemap.append(f"- [{page['title']}]({page['url']})\n") + sitemap.append("\n") + + # Write the complete llms.txt + content = header + terminology + ''.join(sitemap) + + with open(output_path, 'w') as f: + f.write(content) + + print(f"Generated {output_path} with {len(pages)} pages organized into {len(categories)} categories") + + +def generate_docs_content(site_dir: Path, output_path: Path): + """Generate docs-content.txt file for answer engines.""" + pages = get_site_structure(site_dir) + + # Start with introduction + content = """# Flox Documentation Content + +This file contains comprehensive documentation content for answer engines and RAG systems. + +""" + + # Group pages by category and add content + categories = {} + for page in pages: + cat = page['category'] + if cat not in categories: + categories[cat] = [] + categories[cat].append(page) + + # Define category order and titles + category_order = [ + ('overview', 'Overview'), + ('installation', 'Installation'), + ('tutorials', 'Tutorials & Getting Started'), + ('concepts', 'Core Concepts'), + ('languages', 'Language-Specific Guides'), + ('manual', 'Command Reference'), + ('customer', 'Customer Resources'), + ('snippets', 'Code Snippets'), + ('other', 'Other') + ] + + for cat_key, cat_title in category_order: + if cat_key in categories: + content += f"\n## {cat_title}\n\n" + + for page in sorted(categories[cat_key], key=lambda x: x['title']): + content += f"### {page['title']}\n" + content += f"URL: {page['url']}\n\n" + + if page['description']: + content += f"**Description**: {page['description']}\n\n" + + # Try to extract content from the HTML file + html_file = site_dir / page['path'] + try: + with open(html_file, 'r', encoding='utf-8') as f: + html_content = f.read() + + page_content = extract_page_content(html_content) + if page_content and len(page_content) > 200: # Only include substantial content + content += page_content + "\n\n" + else: + content += f"*Content available at: {page['url']}*\n\n" + except Exception as e: + content += f"*Content available at: {page['url']}*\n\n" + + content += "---\n\n" + + # Write the complete docs-content.txt + with open(output_path, 'w') as f: + f.write(content) + + print(f"Generated {output_path} with comprehensive documentation content") + + +def main(): + if len(sys.argv) < 2: + print("Usage: generate_llms_txt.py ") + sys.exit(1) + + site_dir = Path(sys.argv[1]) + + if not site_dir.exists(): + print(f"Error: Directory {site_dir} does not exist") + sys.exit(1) + + # Generate files in temp location first, then copy to site root + import tempfile + import shutil + + with tempfile.TemporaryDirectory() as temp_dir: + temp_path = Path(temp_dir) + llms_temp = temp_path / 'llms.txt' + docs_content_temp = temp_path / 'docs-content.txt' + + print("Generating files for AI systems...") + generate_llms_txt(site_dir, llms_temp) + generate_docs_content(site_dir, docs_content_temp) + + # Copy to site root + llms_final = site_dir / 'llms.txt' + docs_content_final = site_dir / 'docs-content.txt' + + shutil.copy2(llms_temp, llms_final) + shutil.copy2(docs_content_temp, docs_content_final) + + print("✅ Generated both llms.txt (for agents) and docs-content.txt (for answer engines)") + + +if __name__ == '__main__': + main() + + diff --git a/tools/generate_llms_txt.sh b/tools/generate_llms_txt.sh new file mode 100755 index 00000000..9acaacac --- /dev/null +++ b/tools/generate_llms_txt.sh @@ -0,0 +1,19 @@ +#!/usr/bin/env bash + +# Generate AI files for local development +# This script should be run after mkdocs builds the site + +set -euo pipefail + +# Ensure site directory exists +if [ ! -d "site" ]; then + echo "Error: site directory not found. Please run 'mkdocs build' first." + exit 1 +fi + +# Generate both AI files +python3 tools/generate_llms_txt.py ./site + +echo "✅ Generated both llms.txt (for agents) and docs-content.txt (for answer engines)" + + From d14718530d8b80c83a0a609736e331376789fff8 Mon Sep 17 00:00:00 2001 From: Bill LeVine Date: Fri, 10 Apr 2026 11:22:40 -0400 Subject: [PATCH 03/14] fix(llms): curated link list, llms-full.txt from source, fix install URL - Replace auto-generated 88-page sitemap with curated ~30 key links - Add llms-full.txt generated from source Markdown (not HTML parsing) - Rename docs-content.txt to llms-full.txt (standard convention) - Fix URL generation to strip /index suffixes - Explicitly correct install URL: flox.dev/download, not install.flox.dev Co-authored-by: Michael Stahnke Co-authored-by: Claude Sonnet 4.6 (1M context) --- .github/workflows/ci.yml | 2 + README.md | 6 +- tools/README.md | 4 +- tools/generate_llms_txt.py | 259 +++++++++++++++++-------------------- tools/generate_llms_txt.sh | 2 +- 5 files changed, 127 insertions(+), 146 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 42a22a28..62241bc3 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -50,6 +50,8 @@ jobs: python3 tools/generate_llms_txt.py ./site mkdir -p ./public/docs cp -R ./site/* ./public/docs/ + cp ./site/llms.txt ./public/docs/llms.txt + cp ./site/llms-full.txt ./public/docs/llms-full.txt chmod -R +w ./public/docs cp netlify.toml ./public/ diff --git a/README.md b/README.md index afe93e62..b5e7263a 100644 --- a/README.md +++ b/README.md @@ -47,12 +47,12 @@ Once mkdocs service started you can preview the documentation at This documentation site automatically generates AI-friendly files for different use cases: -- **`llms.txt`** - Optimized for AI agents with critical rules, workflows, and organized sitemap -- **`docs-content.txt`** - Comprehensive content for answer engines and RAG systems +- **`llms.txt`** - Optimized for AI agents with critical rules, workflows, and curated link list +- **`llms-full.txt`** - Full content for RAG systems and answer engines, generated from source Markdown These files are automatically generated during the build process and are available at: - `https://flox.dev/docs/llms.txt` -- `https://flox.dev/docs/docs-content.txt` +- `https://flox.dev/docs/llms-full.txt` ## Guidelines diff --git a/tools/README.md b/tools/README.md index 6f687e1b..b9405a88 100644 --- a/tools/README.md +++ b/tools/README.md @@ -8,8 +8,8 @@ This directory contains build tools and utilities for the Flox documentation sit Generates AI-friendly documentation files from the built MkDocs site: -- **`llms.txt`** - Agent-focused file with critical rules, workflows, and organized sitemap -- **`docs-content.txt`** - Answer engine file with comprehensive documentation content +- **`llms.txt`** - Agent-focused file with critical rules, workflows, and curated link list +- **`llms-full.txt`** - Full content for RAG systems and answer engines, generated from source Markdown **Usage:** ```bash diff --git a/tools/generate_llms_txt.py b/tools/generate_llms_txt.py index 89c46e61..06a24dc3 100755 --- a/tools/generate_llms_txt.py +++ b/tools/generate_llms_txt.py @@ -19,6 +19,8 @@ def normalize_url(path: str, base_url: str = "https://flox.dev/docs") -> str: return base_url # Remove .html extension path = path.replace('.html', '') + # Remove trailing /index so URLs are clean (e.g. /docs/foo not /docs/foo/index) + path = re.sub(r'/index$', '', path) return f"{base_url}/{path}" @@ -27,7 +29,7 @@ def extract_title_from_html(html_content: str) -> str: # Check if this is a redirect page if 'Redirecting...' in html_content or 'redirect' in html_content.lower(): return None # Signal this is a redirect page - + # Try to find the first h1 tag h1_match = re.search(r']*>(.*?)', html_content, re.DOTALL) if h1_match: @@ -35,14 +37,14 @@ def extract_title_from_html(html_content: str) -> str: # Remove markdown tags and clean up title = re.sub(r'<[^>]+>', '', title) return title - + # Fallback to title tag title_match = re.search(r'(.*?)', html_content, re.DOTALL) if title_match: title = title_match.group(1).strip() title = title.replace(' - Flox Docs', '').strip() return title - + return "Untitled" @@ -52,7 +54,7 @@ def extract_description_from_html(html_content: str) -> str: desc_match = re.search(r']*>.*?]*>(.*?)

', html_content, re.DOTALL) @@ -64,7 +66,7 @@ def extract_description_from_html(html_content: str) -> str: if len(desc) > 200: desc = desc[:200] + "..." return desc - + return "" @@ -123,7 +125,7 @@ def get_page_description(url: str, title: str) -> str: 'install-flox/uninstall': 'How to uninstall Flox', 'flox-5-minutes': 'Quick start guide to get up and running', } - + # Extract the key part of the URL key = url.replace('https://flox.dev/docs/', '').replace('/index', '') return descriptions.get(key, '') @@ -133,30 +135,30 @@ def get_site_structure(site_dir: Path) -> list: """Get all pages from the built site.""" pages = [] html_files = list(site_dir.rglob('*.html')) - + for html_file in sorted(html_files): # Skip generated JS/search files if html_file.name in ['search.html', '404.html', 'sitemap.xml']: continue - + rel_path = html_file.relative_to(site_dir) url = normalize_url(str(rel_path)) - + try: with open(html_file, 'r', encoding='utf-8') as f: content = f.read() - + title = extract_title_from_html(content) - + # Skip redirect pages if title is None: continue - + description = extract_description_from_html(content) - + description = get_page_description(url, title) category = categorize_page(url, title) - + pages.append({ 'url': url, 'title': title, @@ -166,7 +168,7 @@ def get_site_structure(site_dir: Path) -> list: }) except Exception as e: print(f"Error processing {html_file}: {e}", file=sys.stderr) - + return pages @@ -175,23 +177,23 @@ def extract_page_content(html_content: str) -> str: # Remove script and style elements content = re.sub(r']*>.*?', '', html_content, flags=re.DOTALL) content = re.sub(r']*>.*?', '', content, flags=re.DOTALL) - + # Extract main content area main_match = re.search(r']*>(.*?)', content, re.DOTALL) if main_match: content = main_match.group(1) - + # Remove unwanted elements content = re.sub(r']*>.*?', '', content, flags=re.DOTALL) content = re.sub(r']*>.*?', '', content, flags=re.DOTALL) content = re.sub(r']*>.*?', '', content, flags=re.DOTALL) - + # Remove license/copyright text content = re.sub(r'Permission is hereby granted.*?DEALINGS IN THE SOFTWARE\.', '', content, flags=re.DOTALL) content = re.sub(r'Copyright.*?All rights reserved\.', '', content, flags=re.DOTALL) content = re.sub(r'THE SOFTWARE IS PROVIDED.*?DEALINGS IN THE SOFTWARE\.', '', content, flags=re.DOTALL) content = re.sub(r'-->.*?Have questions\?', '', content, flags=re.DOTALL) - + # Remove HTML tags but preserve structure content = re.sub(r']*>(.*?)', r'\n\n#\1 \2\n', content) content = re.sub(r']*>(.*?)

', r'\1\n\n', content) @@ -199,23 +201,71 @@ def extract_page_content(html_content: str) -> str: content = re.sub(r']*>(.*?)', r'`\1`', content) content = re.sub(r']*>]*>(.*?)', r'```\n\1\n```', content, flags=re.DOTALL) content = re.sub(r'<[^>]+>', '', content) - + # Clean up whitespace and remove empty lines content = re.sub(r'\n\s*\n\s*\n', '\n\n', content) content = re.sub(r'^\s*\n', '', content, flags=re.MULTILINE) content = content.strip() - + # Only return substantial content (more than 100 chars) if len(content) < 100: return "" - + return content +# Curated list of key documentation pages for AI agents. +# Maintained manually to surface the most useful pages rather than +# auto-generating an exhaustive 88-page sitemap. +CURATED_LINKS = [ + ("Getting Started", [ + ("Flox in 5 Minutes", "https://flox.dev/docs/flox-5-minutes/", "Quick start guide"), + ("Install Flox", "https://flox.dev/docs/install-flox/install/", "Install via flox.dev/download"), + ("What is Flox?", "https://flox.dev/docs/", "Overview"), + ]), + ("Core Concepts", [ + ("Environments", "https://flox.dev/docs/concepts/environments/", "What environments are and how they work"), + ("Activation", "https://flox.dev/docs/concepts/activation/", "How to activate — never run interactively"), + ("Catalog & Packages", "https://flox.dev/docs/concepts/packages-and-catalog/", "Package discovery and installation"), + ("Services", "https://flox.dev/docs/concepts/services/", "Running processes in environments"), + ("Generations", "https://flox.dev/docs/concepts/generations/", "Snapshots and rollbacks"), + ("FloxHub", "https://flox.dev/docs/concepts/floxhub/", "Package registry and environment sharing"), + ]), + ("Tutorials", [ + ("Creating Environments", "https://flox.dev/docs/tutorials/creating-environments/", ""), + ("Sharing Environments", "https://flox.dev/docs/tutorials/sharing-environments/", ""), + ("Customizing the Shell", "https://flox.dev/docs/tutorials/customizing-environments/", ""), + ("CI/CD", "https://flox.dev/docs/tutorials/ci-cd/", ""), + ("Layering Environments", "https://flox.dev/docs/tutorials/layering-multiple-environments/", ""), + ("Reusing Environments", "https://flox.dev/docs/tutorials/composition/", ""), + ("Build and Publish", "https://flox.dev/docs/tutorials/build-and-publish/", ""), + ("Multi-arch Environments", "https://flox.dev/docs/tutorials/multi-arch-environments/", ""), + ("CUDA", "https://flox.dev/docs/tutorials/cuda/", ""), + ("Migrate from Homebrew", "https://flox.dev/docs/tutorials/migrations/homebrew/", ""), + ("Migrate from nvm", "https://flox.dev/docs/tutorials/migrations/nvm/", ""), + ("Default Environment", "https://flox.dev/docs/tutorials/default-environment/", ""), + ]), + ("Language Guides", [ + ("Python", "https://flox.dev/docs/languages/python/", ""), + ("Node.js", "https://flox.dev/docs/languages/nodejs/", ""), + ("Go", "https://flox.dev/docs/languages/go/", ""), + ("Rust", "https://flox.dev/docs/languages/rust/", ""), + ("C/C++", "https://flox.dev/docs/languages/c/", ""), + ("JVM", "https://flox.dev/docs/languages/jvm/", ""), + ("Ruby", "https://flox.dev/docs/languages/ruby/", ""), + ]), + ("Reference", [ + ("manifest.toml", "https://flox.dev/docs/reference/command-reference/", "Manifest syntax reference"), + ]), + ("Optional", [ + ("Kubernetes Integration", "https://flox.dev/docs/k8s/intro/", ""), + ("Known Issues", "https://flox.dev/docs/customer/known-issues/", ""), + ]), +] + + def generate_llms_txt(site_dir: Path, output_path: Path): """Generate llms.txt file for agents.""" - pages = get_site_structure(site_dir) - # Read existing llms.txt to get the header existing_llms = Path('docs/llms.txt') header = "" @@ -228,8 +278,8 @@ def generate_llms_txt(site_dir: Path, output_path: Path): header = ''.join(lines[:i]) break header = ''.join(lines) - - # Add key terminology section + + # Add key terminology and quick reference section terminology = """ ## Key Terms - **Environment**: A reproducible development environment with specific packages and configurations @@ -242,6 +292,7 @@ def generate_llms_txt(site_dir: Path, output_path: Path): ## Quick Reference ### Common Workflows +- **Install Flox**: Visit `flox.dev/download` (not install.flox.dev — that does not exist) - **New Project**: `flox init -d .` → `flox install -d . ` → `flox activate -d . -- ` - **Multi-environment Project**: `flox init -d backend` + `flox init -d frontend` - **Sharing Environment**: `flox push` → `flox pull` on another machine @@ -249,151 +300,79 @@ def generate_llms_txt(site_dir: Path, output_path: Path): - **Service Management**: Define in manifest → `flox services start ` → `flox services status` """ - - # Group pages by category - categories = {} - for page in pages: - cat = page['category'] - if cat not in categories: - categories[cat] = [] - categories[cat].append(page) - - # Generate organized sitemap - sitemap = ["## Documentation Structure\n"] - - # Define category order and titles - category_order = [ - ('overview', 'Overview'), - ('installation', 'Installation'), - ('tutorials', 'Tutorials & Getting Started'), - ('concepts', 'Core Concepts'), - ('languages', 'Language-Specific Guides'), - ('manual', 'Command Reference'), - ('customer', 'Customer Resources'), - ('snippets', 'Code Snippets'), - ('other', 'Other') - ] - - for cat_key, cat_title in category_order: - if cat_key in categories: - sitemap.append(f"### {cat_title}\n") - for page in sorted(categories[cat_key], key=lambda x: x['title']): - if page['description']: - sitemap.append(f"- [{page['title']}]({page['url']}) - {page['description']}\n") - else: - sitemap.append(f"- [{page['title']}]({page['url']})\n") - sitemap.append("\n") - + + # Build sitemap from the curated link list + sitemap = ["## Documentation\n\n"] + for section_title, links in CURATED_LINKS: + sitemap.append(f"### {section_title}\n\n") + for title, url, desc in links: + if desc: + sitemap.append(f"- [{title}]({url}): {desc}\n") + else: + sitemap.append(f"- [{title}]({url})\n") + sitemap.append("\n") + # Write the complete llms.txt content = header + terminology + ''.join(sitemap) - + with open(output_path, 'w') as f: f.write(content) - - print(f"Generated {output_path} with {len(pages)} pages organized into {len(categories)} categories") + print(f"Generated {output_path} with {sum(len(links) for _, links in CURATED_LINKS)} curated links") -def generate_docs_content(site_dir: Path, output_path: Path): - """Generate docs-content.txt file for answer engines.""" - pages = get_site_structure(site_dir) - - # Start with introduction - content = """# Flox Documentation Content -This file contains comprehensive documentation content for answer engines and RAG systems. +def generate_llms_full(docs_dir: Path, output_path: Path): + """Generate llms-full.txt from source Markdown files.""" + md_files = sorted(docs_dir.rglob("*.md")) -""" - - # Group pages by category and add content - categories = {} - for page in pages: - cat = page['category'] - if cat not in categories: - categories[cat] = [] - categories[cat].append(page) - - # Define category order and titles - category_order = [ - ('overview', 'Overview'), - ('installation', 'Installation'), - ('tutorials', 'Tutorials & Getting Started'), - ('concepts', 'Core Concepts'), - ('languages', 'Language-Specific Guides'), - ('manual', 'Command Reference'), - ('customer', 'Customer Resources'), - ('snippets', 'Code Snippets'), - ('other', 'Other') - ] - - for cat_key, cat_title in category_order: - if cat_key in categories: - content += f"\n## {cat_title}\n\n" - - for page in sorted(categories[cat_key], key=lambda x: x['title']): - content += f"### {page['title']}\n" - content += f"URL: {page['url']}\n\n" - - if page['description']: - content += f"**Description**: {page['description']}\n\n" - - # Try to extract content from the HTML file - html_file = site_dir / page['path'] - try: - with open(html_file, 'r', encoding='utf-8') as f: - html_content = f.read() - - page_content = extract_page_content(html_content) - if page_content and len(page_content) > 200: # Only include substantial content - content += page_content + "\n\n" - else: - content += f"*Content available at: {page['url']}*\n\n" - except Exception as e: - content += f"*Content available at: {page['url']}*\n\n" - - content += "---\n\n" - - # Write the complete docs-content.txt with open(output_path, 'w') as f: - f.write(content) - - print(f"Generated {output_path} with comprehensive documentation content") + f.write("# Flox Documentation — Full Content\n\n") + f.write("Complete documentation for RAG systems and Cursor @Docs.\n\n") + + for md_file in md_files: + rel = md_file.relative_to(docs_dir) + f.write(f"\n\n---\n\n## {rel}\n\n") + f.write(md_file.read_text(encoding='utf-8')) + + print(f"Generated {output_path} from {len(md_files)} source files") def main(): if len(sys.argv) < 2: print("Usage: generate_llms_txt.py ") sys.exit(1) - + site_dir = Path(sys.argv[1]) - + if not site_dir.exists(): print(f"Error: Directory {site_dir} does not exist") sys.exit(1) - + + # Source markdown lives one level up from the built site + docs_dir = site_dir.parent / "docs" + # Generate files in temp location first, then copy to site root import tempfile import shutil - + with tempfile.TemporaryDirectory() as temp_dir: temp_path = Path(temp_dir) llms_temp = temp_path / 'llms.txt' - docs_content_temp = temp_path / 'docs-content.txt' - + llms_full_temp = temp_path / 'llms-full.txt' + print("Generating files for AI systems...") generate_llms_txt(site_dir, llms_temp) - generate_docs_content(site_dir, docs_content_temp) - + generate_llms_full(docs_dir, llms_full_temp) + # Copy to site root llms_final = site_dir / 'llms.txt' - docs_content_final = site_dir / 'docs-content.txt' - + llms_full_final = site_dir / 'llms-full.txt' + shutil.copy2(llms_temp, llms_final) - shutil.copy2(docs_content_temp, docs_content_final) - - print("✅ Generated both llms.txt (for agents) and docs-content.txt (for answer engines)") + shutil.copy2(llms_full_temp, llms_full_final) + + print("Generated both llms.txt (for agents) and llms-full.txt (for RAG/answer engines)") if __name__ == '__main__': main() - - diff --git a/tools/generate_llms_txt.sh b/tools/generate_llms_txt.sh index 9acaacac..663db93e 100755 --- a/tools/generate_llms_txt.sh +++ b/tools/generate_llms_txt.sh @@ -14,6 +14,6 @@ fi # Generate both AI files python3 tools/generate_llms_txt.py ./site -echo "✅ Generated both llms.txt (for agents) and docs-content.txt (for answer engines)" +echo "Generated both llms.txt (for agents) and llms-full.txt (for RAG/answer engines)" From c8c1572f89fe5809e97a193b07cd785d97c03eb6 Mon Sep 17 00:00:00 2001 From: Bill LeVine Date: Fri, 10 Apr 2026 11:34:14 -0400 Subject: [PATCH 04/14] chore: replace gnumake/Makefile with just/justfile - Swap gnumake for just in the Flox environment manifest - Replace Makefile with a justfile (same recipes: dev, build, clean) - Update README to reference just commands Co-authored-by: Claude Sonnet 4.6 (1M context) --- .flox/env/manifest.toml | 2 +- Makefile | 43 -- README.md | 10 +- docs/reference/command-reference/README.md | 12 + .../command-reference/flox-activate.md | 204 ++++++++ docs/reference/command-reference/flox-auth.md | 44 ++ .../command-reference/flox-config.md | 134 +++++ .../command-reference/flox-containerize.md | 105 ++++ .../command-reference/flox-delete.md | 66 +++ docs/reference/command-reference/flox-edit.md | 105 ++++ docs/reference/command-reference/flox-envs.md | 59 +++ docs/reference/command-reference/flox-init.md | 73 +++ .../command-reference/flox-install.md | 121 +++++ docs/reference/command-reference/flox-list.md | 67 +++ docs/reference/command-reference/flox-pull.md | 84 ++++ docs/reference/command-reference/flox-push.md | 73 +++ .../command-reference/flox-search.md | 82 +++ .../command-reference/flox-services-logs.md | 107 ++++ .../flox-services-restart.md | 91 ++++ .../command-reference/flox-services-start.md | 96 ++++ .../command-reference/flox-services-status.md | 81 +++ .../command-reference/flox-services-stop.md | 89 ++++ docs/reference/command-reference/flox-show.md | 72 +++ .../command-reference/flox-uninstall.md | 67 +++ .../command-reference/flox-update.md | 79 +++ .../command-reference/flox-upgrade.md | 73 +++ docs/reference/command-reference/flox.md | 141 ++++++ .../command-reference/manifest.toml.md | 475 ++++++++++++++++++ justfile | 28 ++ 29 files changed, 2634 insertions(+), 49 deletions(-) delete mode 100644 Makefile create mode 100644 docs/reference/command-reference/README.md create mode 100644 docs/reference/command-reference/flox-activate.md create mode 100644 docs/reference/command-reference/flox-auth.md create mode 100644 docs/reference/command-reference/flox-config.md create mode 100644 docs/reference/command-reference/flox-containerize.md create mode 100644 docs/reference/command-reference/flox-delete.md create mode 100644 docs/reference/command-reference/flox-edit.md create mode 100644 docs/reference/command-reference/flox-envs.md create mode 100644 docs/reference/command-reference/flox-init.md create mode 100644 docs/reference/command-reference/flox-install.md create mode 100644 docs/reference/command-reference/flox-list.md create mode 100644 docs/reference/command-reference/flox-pull.md create mode 100644 docs/reference/command-reference/flox-push.md create mode 100644 docs/reference/command-reference/flox-search.md create mode 100644 docs/reference/command-reference/flox-services-logs.md create mode 100644 docs/reference/command-reference/flox-services-restart.md create mode 100644 docs/reference/command-reference/flox-services-start.md create mode 100644 docs/reference/command-reference/flox-services-status.md create mode 100644 docs/reference/command-reference/flox-services-stop.md create mode 100644 docs/reference/command-reference/flox-show.md create mode 100644 docs/reference/command-reference/flox-uninstall.md create mode 100644 docs/reference/command-reference/flox-update.md create mode 100644 docs/reference/command-reference/flox-upgrade.md create mode 100644 docs/reference/command-reference/flox.md create mode 100644 docs/reference/command-reference/manifest.toml.md create mode 100644 justfile diff --git a/.flox/env/manifest.toml b/.flox/env/manifest.toml index 5b1048d9..f98239d0 100644 --- a/.flox/env/manifest.toml +++ b/.flox/env/manifest.toml @@ -23,7 +23,7 @@ markdownlint-cli2.pkg-path = "markdownlint-cli2" markdownlint-cli2.pkg-group = "lint" curl.pkg-path = "curl" curl.outputs = "all" -gnumake.pkg-path = "gnumake" +just.pkg-path = "just" [hook] on-activate = ''' diff --git a/Makefile b/Makefile deleted file mode 100644 index f034cd9c..00000000 --- a/Makefile +++ /dev/null @@ -1,43 +0,0 @@ -# Flox Documentation Makefile - -.PHONY: help dev build clean install - -# Default target -help: - @echo "Available targets:" - @echo " dev - Start development server with live reload" - @echo " build - Build static site and generate AI files" - @echo " clean - Clean build artifacts" - @echo " install - Install dependencies" - @echo " help - Show this help message" - -# Development server with live reload -dev: - @echo "Starting development server..." - @echo "Site will be available at: http://127.0.0.1:8000" - @echo "Press Ctrl+C to stop" - mkdocs serve - -# Build static site and generate AI files -build: - @echo "Building static site..." - mkdocs build - @echo "Generating AI files..." - python3 tools/generate_llms_txt.py ./site - @echo "✅ Build complete! Site available in ./site/" - -# Clean build artifacts -clean: - @echo "Cleaning build artifacts..." - rm -rf site/ - rm -rf public/ - @echo "✅ Clean complete!" - -# Install dependencies (if needed) -install: - @echo "Installing dependencies..." - @if command -v poetry >/dev/null 2>&1; then \ - poetry install; \ - else \ - echo "Poetry not found. Please install dependencies manually."; \ - fi diff --git a/README.md b/README.md index b5e7263a..be795a3b 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ $ flox activate ✅ You are now using the environment 'floxdocs'. # Start development server -λ (floxdocs) $ make dev +λ (floxdocs) $ just dev ``` The documentation will be available at `http://127.0.0.1:8000` with live reload. @@ -20,10 +20,10 @@ The documentation will be available at `http://127.0.0.1:8000` with live reload. ### Available Commands ```bash -make dev # Start development server with live reload -make build # Build static site and generate AI files -make clean # Clean build artifacts -make help # Show all available commands +just dev # Start development server with live reload +just build # Build static site and generate AI files +just clean # Clean build artifacts +just # Show all available commands ``` ### Flox Native Usage diff --git a/docs/reference/command-reference/README.md b/docs/reference/command-reference/README.md new file mode 100644 index 00000000..843785de --- /dev/null +++ b/docs/reference/command-reference/README.md @@ -0,0 +1,12 @@ +--- +title: README +description: Command reference for the `README` command. +--- + +# `README` command +--- +title: README +description: Command reference for the `README` command. +--- + +# `README` command diff --git a/docs/reference/command-reference/flox-activate.md b/docs/reference/command-reference/flox-activate.md new file mode 100644 index 00000000..a6d86dee --- /dev/null +++ b/docs/reference/command-reference/flox-activate.md @@ -0,0 +1,204 @@ +--- +title: flox activate +description: Command reference for the `flox activate` command. +--- + +# `flox activate` command + +## NAME + +flox-activate - activate environments + +## SYNOPSIS + + flox [] activate + [-d= | -r=/] + [-t] + [--print-script] + [-- []] + +## DESCRIPTION + +Sets environment variables and aliases, runs hooks, starts services, and +adds `bin` directories to your `$PATH`. + +`flox activate` may run in one of three modes: + +- interactive: `flox activate` when invoked from an interactive shell + Launches an interactive sub-shell. The shell to be launched is + determined by `$FLOX_SHELL` or `$SHELL`. +- command: `flox activate -- CMD` + Executes `CMD` in the same environment as if run inside an interactive + shell produced by an interactive `flox activate` The shell `CMD` is + run by is determined by `$FLOX_SHELL` or `$SHELL`. +- in-place: `flox activate` when invoked from an non-interactive shell + with it’s `stdout` redirected e.g. `eval "$(flox activate)"` + Produces commands to be sourced by the parent shell. Flox will + determine the parent shell from `$FLOX_SHELL` or otherwise + automatically determine the parent shell and fall back to `$SHELL`. + +`flox activate` currently supports `bash`, `fish`, `tcsh`, and `zsh` +shells for any of the detection mechanisms described above. + +When invoked interactively, the shell prompt will be modified to display +the active environments, as shown below: + + flox [env1 env2 env3] + +When multiple environments are activated each of their shell hooks +(`profile` and `hook` scripts) are executed in the context of the +environment that they come from. This means that for each shell hook +various environment variables such as `PATH`, `MANPATH`, +`PKG_CONFIG_PATH`, `PYTHONPATH`, etc, are set to the appropriate values +for the environment in which the shell hook was defined. See +[`manifest.toml(5)`](./manifest.toml.md) for more details on shell +hooks. + +## OPTIONS + +### Activate Options + +`-- []` +Command to run in the environment. Spawns the command in a subshell that +does not leak into the calling process. + +`-t`, `--trust` +Trust a remote environment for this activation. Activating an +environment executes a shell hook which may execute arbitrary code. This +presents a security risk, so you will be prompted whether to trust the +environment. Environments owned by the current user and Flox are always +trusted. You may set certain environments to always be trusted using the +config key `trusted_environments."" = (trust | deny)`, or +via the following command: +`flox config --set trusted_environments.\"\" trust`. + +`--print-script` +Prints an activation script to `stdout` that’s suitable for sourcing in +a shell rather than activation via creating a subshell. `flox` +automatically knows when to print the activation script to `stdout`, so +this command is just a debugging aid for users. + +`-s`, `--start-services` +Start the services listed in the manifest when activating the +environment. If no services are running, the services from the manifest +will be started, otherwise a warning will displayed and activation will +continue. + +This flag is currently incompatible with “in-place” activations and +remote environments, but these features will be added in the future. + +The services started with this flag will be cleaned up once the last +activation of this environment terminates. + +A remote environment can only have a single set of running services, +regardless of how many times the environment is activated concurrently. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## ENVIRONMENT VARIABLES + +### Variables set by `flox activate` + +`$FLOX_ENV` +Contains the path to the built environment. This directory contains a +merged set of `bin`, `lib`, etc directories for all the packages in the +environment. + +`$FLOX_PROMPT_ENVIRONMENTS` +Contains a space-delimited list of the active environments, +e.g. `owner1/foo owner2/bar local_env`. If, `hide_default_prompt` is set +to `true`, environments named `default` are excluded. + +`$FLOX_ENV_CACHE` +`activate` sets this variable to a directory that can be used by an +environment’s hook to store transient files. These files will persist +for environments used locally, but they will not be pushed, and they +will not persist when using a remote environment with `-r`. + +`$FLOX_ENV_PROJECT` +`activate` sets this variable to the directory of the project using the +flox environment. For environments stored locally, this is the directory +containing the environment. When running `flox activate -r`, this is set +to the current working directory. This variable can be used to find +project files in environment hooks. + +`$_FLOX_ACTIVE_ENVIRONMENTS` +A JSON array containing one object per active environment. This is +currently an implementation detail and its contents are subject to +change. + +`$FLOX_ACTIVATE_START_SERVICES` +`"true"` if this activation started services, `"false"` otherwise. + +### Variables used by `flox activate` + +`$FLOX_SHELL` +When launching an interactive sub-shell, Flox launches the shell +specified in `$FLOX_SHELL` if it is set. When printing a shell for +sourcing in the current shell, Flox will produce a script suitable for +`$FLOX_SHELL` if it is set. + +`$SHELL` +When launching an interactive sub-shell, Flox launches the shell +specified in `$SHELL` if it is set and `$FLOX_SHELL` is not set. When +printing a shell for sourcing in the current shell, Flox will produce a +script suitable for `$SHELL` if it is set and `$FLOX_SHELL` is not set +and Flox can’t detect the parent shell. + +`$FLOX_PROMPT_COLOR_{1,2}` +Flox adds text to the beginning of the shell prompt to indicate which +environments are active. A set of default colors are used to color this +prompt, but the colors may be overridden with the `$FLOX_PROMPT_COLOR_1` +and `$FLOX_PROMPT_COLOR_2` environment variables. + +The values of these variables should be integers chosen from the +256-color palette as described in the [xterm-256color +chart](https://upload.wikimedia.org/wikipedia/commons/1/15/Xterm_256color_chart.svg). + +## EXAMPLES: + +Activate an environment stored in the current directory: + + $ flox activate + +Activate an environment `some_user/myenv` that’s been pushed to FloxHub: + + $ flox activate -r some_user/myenv + +Invoke a command inside an environment without entering its subshell: + + $ flox activate -- cmd --some-arg arg1 arg2 + +Activate `default` Flox environment only within the current shell (add +to the relevant “rc” file, e.g. `~/.bashrc` or `~/.zprofile`): + + $ eval "$(flox activate)" + +## SEE ALSO + +[`flox-push(1)`](./flox-push.md), [`flox-pull(1)`](./flox-pull.md), +[`flox-edit(1)`](./flox-edit.md), [`flox-delete(1)`](./flox-delete.md) diff --git a/docs/reference/command-reference/flox-auth.md b/docs/reference/command-reference/flox-auth.md new file mode 100644 index 00000000..b0a8a271 --- /dev/null +++ b/docs/reference/command-reference/flox-auth.md @@ -0,0 +1,44 @@ +--- +title: flox auth +description: Command reference for the `flox auth` command. +--- + +# `flox auth` command + +## NAME + +flox-auth - FloxHub authentication commands + +## SYNOPSIS + + flox [] auth + (login | logout | status) + +## DESCRIPTION + +Authenticate with FloxHub so that you can push and pull environments. + +## OPTIONS + +### `login` + +Logs in to FloxHub. + +Required to interact with environments on FloxHub via `flox push`, +`flox pull`, and `flox activate -r`. Authenticating also automatically +trusts your personal environments. + +Prompts you to enter a one-time code at a specified URL. If called +interactively it can open the browser for you if you press ``. + +See also: [`flox-push(1)`](./flox-push.md), +[`flox-pull(1)`](./flox-pull.md), +[`flox-activate(1)`](./flox-activate.md) + +### `logout` + +Logs out from FloxHub. + +### `status` + +Print your current login status diff --git a/docs/reference/command-reference/flox-config.md b/docs/reference/command-reference/flox-config.md new file mode 100644 index 00000000..a26d1c61 --- /dev/null +++ b/docs/reference/command-reference/flox-config.md @@ -0,0 +1,134 @@ +--- +title: flox config +description: Command reference for the `flox config` command. +--- + +# `flox config` command + +## NAME + +flox-config - view and set configuration options + +## SYNOPSIS + + flox [] config + [-l | + -r | + --set | + --set-number | + --set-bool | + --delete=] + +## DESCRIPTION + +Without any flags or when `-l` is passed, `flox config` shows all +options with their computed value. + +Config values are read from the following sources in order of descending +priority: + +1. Environment variables. All config options may be set by prefixing + with `FLOX_` and using SCREAMING_SNAKE_CASE. For example, + `disable_metrics` may be set with `FLOX_DISABLE_METRICS=true`. +2. User customizations from `$FLOX_CONFIG_DIR/flox.toml` if set or else + `$XDG_CONFIG_HOME/flox/flox.toml`. +3. User customizations from `flox/flox.toml` in any of + `$XDG_CONFIG_DIRS`. +4. System settings from `/etc/flox.toml`. +5. `flox` provided defaults. + +`flox config` commands that mutate configuration always write to +`${FLOX_CONFIG_DIR:-$XDG_CONFIG_HOME}/flox/flox.toml`. + +### Key Format + +`` supports dot-separated queries for nested values, for example: + + flox config --set 'trusted_environments."owner/name"' trust + +## OPTIONS + +### Config Options + +`-l`, `--list` +List the current values of all options. + +`-r`, `--reset` +Reset all options to their default values without confirmation. + +`--set ` +Set ` = ` for string values + +`--set-number ` +Set ` = ` for number values + +`--set-bool ` +Set ` = ` for boolean values + +`--delete ` +Delete config key + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SUPPORTED CONFIGURATION OPTIONS + +`config_dir` +Directory where flox should load its configuration file (default: +`$XDG_CONFIG_HOME/flox`). This option will only take effect if set with +`$FLOX_CONFIG_DIR`. `$FLOX_CONFIG_DIR` and `config_dir` are ignored. + +`cache_dir` +Directory where flox should store ephemeral data (default: +`$XDG_CACHE_HOME/flox`). + +`data_dir` +Directory where flox should store persistent data (default: +`$XDG_DATA_HOME/flox`). + +`disable_metrics` +Disable collecting and sending usage metrics. + +`floxhub_token` +Token to authenticate on FloxHub. + +`hide_default_prompt` +Hide environments named ‘default’ from the shell prompt, and don’t add +environments named ‘default’ to `$FLOX_PROMPT_ENVIRONMENTS` (default: +false). + +`search_limit` +How many items `flox search` should show by default. + +`set_prompt` +Set shell prompt when activating an environment (default: true). + +`shell_prompt` - DEPRECATED +Rule whether to change the shell prompt in activated environments +(default: “show-all”). This has been deprecated in favor of `set_prompt` +and `hide_default_prompt`. Possible values are \* “show-all”: shows all +active anvironments \* “hide-all”: disables the modification of the +shell prompt \* “hide-default”: filters out environments named ‘default’ +from the shell prompt + +`trusted_environments` +Remote environments that are trusted for activation. Contains keys of +the form `"/"` that map to either `"trust"` or `"deny"`. + +## ENVIRONMENT VARIABLES + +`$FLOX_DISABLE_METRICS` +Variable for disabling the collection/sending of metrics data. If set to +`true`, prevents Flox from submitting basic metrics information such as +a unique token and the subcommand issued. diff --git a/docs/reference/command-reference/flox-containerize.md b/docs/reference/command-reference/flox-containerize.md new file mode 100644 index 00000000..58881cd4 --- /dev/null +++ b/docs/reference/command-reference/flox-containerize.md @@ -0,0 +1,105 @@ +--- +title: flox containerize +description: Command reference for the `flox containerize` command. +--- + +# `flox containerize` command + +> **Warning:** This command is **experimental** and its behaviour is +> subject to change + +## NAME + +flox-containerize - export an environment as a container image + +## SYNOPSIS + + flox [] containerize + [-d= | -r=] + [-o=] + +## DESCRIPTION + +Export a Flox environment as a container image. The image is written to +``. Then use `docker load -i ` to load the image into +docker. When `` is `-`, the image is written to `stdout`, and can +be piped into `docker load` directly. + +Running the container will behave like running `flox activate`. Running +the container interactively with `docker run -it `, will +launch a bash subshell in the container with all your packages and +variables set after running the activation hook. This is akin to +`flox activate` + +Running the container non-interactively with `docker run ` +allows you to run a command within the container without launching a +subshell, similar to `flox activate --` + +**Note**: The `containerize` command is currently **only available on +Linux**. The produced container however can also run on macOS. + +## OPTIONS + +`-o`, `--output` +Write the container to `` (default: +`./-container.tar`) If `` is `-`, writes to +`stdout`. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## EXAMPLES + +Create a container image file and load it into Docker: + + $ flox containerize -o ./mycontainer.tar + $ docker load -i ./mycontainer.tar + +Pipe the image into Docker directly: + + $ flox containerize -o - | docker load + +Run the container interactively: + + $ flox init + $ flox install hello + $ flox containerize -o - | docker load + $ docker run --rm -it + [floxenv] $ hello + Hello, world! + +Run a specific command from within the container, but do not launch a +subshell. + + $ flox init + $ flox install hello + $ flox containerize -o - | docker load + $ docker run hello + Hello, world + +## SEE ALSO + +[`flox-activate(1)`](./flox-activate.md) \[`docker-load(1)`\] diff --git a/docs/reference/command-reference/flox-delete.md b/docs/reference/command-reference/flox-delete.md new file mode 100644 index 00000000..c246351f --- /dev/null +++ b/docs/reference/command-reference/flox-delete.md @@ -0,0 +1,66 @@ +--- +title: flox delete +description: Command reference for the `flox delete` command. +--- + +# `flox delete` command + +## NAME + +flox-delete - delete an environment + +## SYNOPSIS + + flox [] delete + [-f] + [-d=] + +## DESCRIPTION + +Deletes all data pertaining to an environment. By default only the +environment in the current directory is deleted, but environments in +other directories may be deleted via the `-d` flag. + +By default you will be prompted for a confirmation before deleting the +environment. The `-f` flag skips the confirmation dialog and is required +for non-interactive use. + +## OPTIONS + +### Delete Options + +`-f`, `--force` +Delete the environment without confirmation. + + + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## See Also + +[`flox-init(1)`](./flox-init.md) [`flox-push(1)`](./flox-push.md), +[`flox-pull(1)`](./flox-pull.md) diff --git a/docs/reference/command-reference/flox-edit.md b/docs/reference/command-reference/flox-edit.md new file mode 100644 index 00000000..35e05df6 --- /dev/null +++ b/docs/reference/command-reference/flox-edit.md @@ -0,0 +1,105 @@ +--- +title: flox edit +description: Command reference for the `flox edit` command. +--- + +# `flox edit` command + +## NAME + +flox-edit - edit the declarative environment configuration + +## SYNOPSIS + + flox [] edit + [-d= | -r=] + [[-f=] | -n= | --sync | --reset] + +## DESCRIPTION + +### Transactionally edit the environment manifest. + +By default invokes an editor with a copy of the local manifest for the +user to interactively edit. The editor is found by querying `$EDITOR`, +`$VISUAL`, and then by looking for common editors in `$PATH`. The +manifest of an environment on FloxHub or in a different directory can be +edited via the `-r` or `-d` flags respectively. See +[`manifest.toml(5)`](./manifest.toml.md) for more details on the +manifest format. + +Once the editor is closed the environment is built in order to validate +the edit. If the build fails you are given a change to continue editing +the manifest, and if you decline, the edit is discarded. This +transactional editing prevents an edit from leaving the environment in a +broken state. One exception is the `-n` flag, which renames a local +environment but does not rebuild it. + +The environment can be edited non-interactively via the `-f` flag, which +replaces the contents of the manifest with those of the provided file. + +### Sync the local manifest with the current generation. + +When using environments that were pushed to or pulled from FloxHub, +changes to the local manifest in `.flox/env/manifest.toml` will block +the use of the environment commands +`flox {install, uninstall, edit, upgrade}`. In this case, a new +generation has to be created from the local manifest first or the +changes discarded. Run `flox edit --reset` to discard local changes and +reset to the current latest generation, or `flox edit --sync` to create +a new generation. + +## OPTIONS + +### Edit Options + +`-f`, `--file` +Replace environment manifest with that in ``. If `` is `-`, +reads from stdin. + +`-n`, `--name` +Rename the environment to ``. Only works for local environments. + +`-s`, `--sync` +Create a new generation from the current local environment (Only +available for managed environments) + +`-r`, `--reset` +Reset the environment to the current generation (Only available for +managed environments) + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## ENVIRONMENT VARIABLES + +`$EDITOR`, `$VISUAL` +Override the default editor used for editing environment manifests and +commit messages. + +## SEE ALSO + +[`flox-push(1)`](./flox-push.md), [`flox-pull(1)`](./flox-pull.md), +[`flox-activate(1)`](./flox-activate.md) diff --git a/docs/reference/command-reference/flox-envs.md b/docs/reference/command-reference/flox-envs.md new file mode 100644 index 00000000..c56a704d --- /dev/null +++ b/docs/reference/command-reference/flox-envs.md @@ -0,0 +1,59 @@ +--- +title: flox envs +description: Command reference for the `flox envs` command. +--- + +# `flox envs` command + +## NAME + +flox-envs - show active and available environments + +## SYNOPSIS + + flox [] envs + [--active] + [--json] + +## DESCRIPTION + +This command can be used to list available environments on the local +machine. When one or more environments are active, the last activated +environment will be listed first and printed in **bold**. + +Whenever an environment is used with any `flox` command it is registered +to a user specific global registry. `flox envs` will list all +environments known to it through the registry. Environments that are +present on the local system may not show up until they are used the +first time. Similarly, if an environment is changed (e.g. deleted and +replaced by an environment with different metadata), the change may not +show until the new environment is used. + +## OPTIONS + +### Edit Options + +`--active` +Show only active environments + +`--json` +Format the output as JSON + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-init(1)`](./flox-init.md), [`flox-pull(1)`](./flox-pull.md), +[`flox-activate(1)`](./flox-activate.md) diff --git a/docs/reference/command-reference/flox-init.md b/docs/reference/command-reference/flox-init.md new file mode 100644 index 00000000..78fe9c38 --- /dev/null +++ b/docs/reference/command-reference/flox-init.md @@ -0,0 +1,73 @@ +--- +title: flox init +description: Command reference for the `flox init` command. +--- + +# `flox init` command + +## NAME + +flox-init - initialize a Flox environment + +## SYNOPSIS + + flox [] init + [-n ] + [-d ] + [--auto-setup] + +## DESCRIPTION + +Create a new empty environment in the current directory. + +The name of the environment will be the basename of the current +directory or `default` if the current directory is `$HOME`. The `--name` +flag can be used to give the environment a specific name. + +By default the environment will be created in the current directory. +Flox will add a directory `$PWD/.flox` containing all relevant +environment metadata. The `--dir` flag can be used to create an +environment in another location. + +If an environment already exists in the current directory, or the path +specified using `--dir` exists, an error is returned. + +`init` will try to detect languages being used in the containing +directory, and it will prompt with suggestions for packages or +activation scripts to be added to the environment. These suggestions can +be taken without prompting by passing `--auto-setup`. The suggestions +can be accepted but then edited using `flox edit`. Currently, +suggestions are made for Python and Nodejs. + +## OPTIONS + +### Init Options + +`-n `, `--name ` +What to name the new environment (default: current directory). + +`-d `, `--dir ` +Directory to create the environment in (default: current directory). + +`--auto-setup` +Apply Flox recommendations for the environment based on what languages +are being used in the containing directory. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-activate(1)`](./flox-activate.md), +[`flox-install(1)`](./flox-install.md), diff --git a/docs/reference/command-reference/flox-install.md b/docs/reference/command-reference/flox-install.md new file mode 100644 index 00000000..fb345ec6 --- /dev/null +++ b/docs/reference/command-reference/flox-install.md @@ -0,0 +1,121 @@ +--- +title: flox install +description: Command reference for the `flox install` command. +--- + +# `flox install` command + +## NAME + +flox-install - install packages to an environment + +## SYNOPSIS + + flox [] install + [-i ] + [[-i ] ] ... + +## DESCRIPTION + +Install packages to an environment. + +Package installation is transactional. During an installation attempt +the environment is built in order to validate that the environment isn’t +broken (for example, in rare cases packages may provide files that +conflict). If building the environment fails, including any of the +consitituent packages, the attempt is discarded and the environment is +unmodified. If the build succeeds, the environment is atomically +updated. + +If a requested package is already installed, nothing is done. If +multiple packages are requested and some of them are already installed, +only the new packages are installed and the transaction will still +succeed as long as the build succeeds. + +You may also specify packages to be installed via +[`flox-edit(1)`](./flox-edit.md), which allows specifying a variety of +options for package installation. See +[`manfifest-toml(1)`](./manifest.toml.md) for more details on the +available options. + +### Install ID + +The name of a package as it exists in the manifest is referred to as the +“install ID”. This ID is separate from the pkg-path and provides a +shorthand for packages with long names such as `python310Packages.pip`. +Install IDs also provide a way to give packages more semantically +meaningful, convenient, or aesthetically pleasing names in the manifest +(e.g. `node21` instead of `nodejs_21`). When not explicitly provided, +the install ID is inferred based on the pkg-path. For pkg-paths that +consist of a single attribute (e.g. `ripgrep`) the install ID is set to +that attribute. For pkg-paths that consist of multiple attributes +(e.g. `python310Packages.pip`) the install ID is set to the last +attribute in the pkg-path (e.g. `pip`). + +As an advanced feature, a Nix flake installable may be specified instead +of a pkg-path, and in this case the install ID is inferred from the +attribute path specified, or if no attribute path is provided, the +install ID is inferred from the flake reference. + +### Package names + +Packages are organized in a hierarchical structure such that certain +packages are found at the top level (e.g. `ripgrep`), and other packages +are found under package sets (e.g. `python310Packages.pip`). We call +this location within the catalog the “pkg-path”. + +The pkg-path is searched when you execute a `flox search` command. The +pkg-path is what’s shown by `flox show`. Finally, the pkg-path appears +in your manifest after a `flox install`. + +``` toml +[install] +ripgrep.pkg-path = "ripgrep" +pip.pkg-path = "python310Packages.pip" +``` + +## OPTIONS + +### Install Options + +`-i`, `--id` +The install ID of the package as it will appear in the manifest + +`` +The pkg-path of the package to install as shown by ‘flox search’ Append +`@` to specify a version requirement. + +Alternatively, an arbitrary Nix flake installable may be specified. See +[`manfifest-toml(1)`](./manifest.toml.md) for more details. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +### SEE ALSO + +[`flox-uninstall(1)`](./flox-uninstall.md), +[`flox-edit(1)`](./flox-edit.md), +[`manifest.toml(5)`](./manifest.toml.md) diff --git a/docs/reference/command-reference/flox-list.md b/docs/reference/command-reference/flox-list.md new file mode 100644 index 00000000..99230e0e --- /dev/null +++ b/docs/reference/command-reference/flox-list.md @@ -0,0 +1,67 @@ +--- +title: flox list +description: Command reference for the `flox list` command. +--- + +# `flox list` command + +## NAME + +flox-list - list packages installed in an environment + +## SYNOPSIS + + flox [] list + [-d= | -r=] + [-e | -c | -n | -a] + +## DESCRIPTION + +List packages installed in an environment. The options `-n`, `-e`, and +`-a` exist to provide varying levels of detail in the output. + +## OPTIONS + +### List Options + +`-e`, `--extended` +Show the install ID, pkg-path, and version of each package (default). + +`-c`, `--config` +Show the raw contents of the manifest. + +`-n`, `--name` +Show only the install ID of each package. + +`-a`, `--all` +Show all available package information including priority and license. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-install(1)`](./flox-install.md) diff --git a/docs/reference/command-reference/flox-pull.md b/docs/reference/command-reference/flox-pull.md new file mode 100644 index 00000000..33320b27 --- /dev/null +++ b/docs/reference/command-reference/flox-pull.md @@ -0,0 +1,84 @@ +--- +title: flox pull +description: Command reference for the `flox pull` command. +--- + +# `flox pull` command + +## NAME + +flox-pull - pull environment from FloxHub + +## SYNOPSIS + + flox [] pull + [-d=] + [-a] + [-r=/ | / | [-f]] + +## DESCRIPTION + +Pull an environment from FloxHub and create a local reference to it, or, +if an environment has already been pulled, retrieve any updates. + +When pulling an environment for the first time, `-d` specifies the +directory in which to create that environment. The remote environment is +specified in the form `/`. It may optionally be preceded by +`-r`, but `-r` is not necessary and is accepted simply for consistency +with other environment commands. + +When pulling an environment that has already been pulled, `-d` specifies +which environment to sync. If `-d` is not specified and the current +directory contains an environment, that environment is synced. `-f` may +only be specified in this case, forceably updating the environment +locally even if there are local changes not reflected in the remote +environment. `/` may be specified in this case and will +replace the environment with the specified environment. + +A remote environment may not support the architecture or operating +system of the local system pulling the environment, in which case `-a` +may be passed to forceably add the current system to the environment’s +manifest. This may create a broken environment that cannot be pushed +back to FloxHub until it is repaired with +[`flox-edit(1)`](./flox-edit.md). See +[`manifest.toml(5)`](./manifest.toml.md) for more on multi-system +environments. + +## OPTIONS + +### Pull Options + +`-d`, `--dir` +Directory to pull an environment into, or directory that contains an +environment that has already been pulled (default: current directory). + +`-a`, `--add-system` +Forceably add current system to the environment, even if incompatible. + +`-r /`, `--remote /` +ID of the environment to pull. + +`/` +ID of the environment to pull. + +`-f`, `--force` +Forceably overwrite the local copy of the environment. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-push(1)`](./flox-push.md) [`flox-edit(1)`](./flox-edit.md) +[`manifest.toml(5)`](./manifest.toml.md) diff --git a/docs/reference/command-reference/flox-push.md b/docs/reference/command-reference/flox-push.md new file mode 100644 index 00000000..b8e36b06 --- /dev/null +++ b/docs/reference/command-reference/flox-push.md @@ -0,0 +1,73 @@ +--- +title: flox push +description: Command reference for the `flox push` command. +--- + +# `flox push` command + +## NAME + +flox-push - send environment to FloxHub + +## SYNOPSIS + + flox [] push + [-d=] + [-o=] + [-f] + +## DESCRIPTION + +Move an environment’s manifest to FloxHub or sync local changes to an +environment to FloxHub. + +After pushing, the remote environment can be referred to as +`/`. + +A path environment contains a manifest file and lock file which are +stored locally and possibly committed to version control. Pushing the +environment moves the manifest and lock file to FloxHub, leaving a +reference to the revision of the environment stored locally. + +Once the environment has been pushed, it can be used directly with the +`--remote` option, or it can be used and edited locally before syncing +with `flox push`. See [`flox-edit(1)`](./flox-edit.md), +[`flox-install(1)`](./flox-install.md), and +[`flox-uninstall(1)`](./flox-uninstall.md) for editing the environment. + +In the same way as a git repo, local changes to an environment that has +been pushed may diverge from the environment on FloxHub if `flox push` +is run from a different host. Passing `--force` to `flox push` will +cause it to overwrite any changes on FloxHub with local changes to the +environment. + +## OPTIONS + +### Push Options + +`-d`, `--dir` +Directory to push the environment from (default: current directory). + +`-o`, `--owner` +FloxHub owner to push environment to (default: current FloxHub user). + +`-f`, `--force` +Forceably overwrite the remote copy of the environment. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-pull(1)`](./flox-pull.md) diff --git a/docs/reference/command-reference/flox-search.md b/docs/reference/command-reference/flox-search.md new file mode 100644 index 00000000..9cd5468b --- /dev/null +++ b/docs/reference/command-reference/flox-search.md @@ -0,0 +1,82 @@ +--- +title: flox search +description: Command reference for the `flox search` command. +--- + +# `flox search` command + +## NAME + +flox-search - search for packages + +## SYNOPSIS + + flox [] search + [--json] + [-a] + + +## DESCRIPTION + +Search for available packages. + +A limited number of search results are reported by default for brevity. +The full result set can be returned via the `-a` flag. + +Only the package name and description are shown by default. Structured +search results can be returned via the `--json` flag. More specific +information for a single package is available via the +[`flox-show(1)`](./flox-show.md) command. + +### Package names + +Packages are organized in a hierarchical structure such that certain +packages are found at the top level (e.g. `ripgrep`), and other packages +are found under package sets (e.g. `python310Packages.pip`). We call +this location within the catalog the “pkg-path”. + +The pkg-path is searched when you execute a `flox search` command. The +pkg-path is what’s shown by `flox show`. Finally, the pkg-path appears +in your manifest after a `flox install`. + +``` toml +[install] +ripgrep.pkg-path = "ripgrep" +pip.pkg-path = "python310Packages.pip" +``` + +### Fuzzy search + +`flox search` uses a fuzzy search mechanism that tries to match either +some portion of the pkg-path or description. + +## OPTIONS + +### Search Options + +`` +The package name to search for. + +`--json` +Display the search results in JSON format. + +`-a`, `--all` +Display all search results (default: at most 10). + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-show(1)`](./flox-show.md) diff --git a/docs/reference/command-reference/flox-services-logs.md b/docs/reference/command-reference/flox-services-logs.md new file mode 100644 index 00000000..e153762e --- /dev/null +++ b/docs/reference/command-reference/flox-services-logs.md @@ -0,0 +1,107 @@ +--- +title: flox services logs +description: Command reference for the `flox services logs` command. +--- + +# `flox services logs` command + +## NAME + +flox-services-logs - show logs of services + +## SYNOPSIS + + flox [] services logs + [-d= | -r=] + [--follow] + [-n=] + [] ... + +## DESCRIPTION + +Display the logs of the specified services. + +If no services are specified, then the `--follow` flag is required and +logs from all services will be printed in real time. + +One or more service names specified with the `--follow` flag will follow +the logs for the specified services. + +If a service name is supplied without the `--follow` flag then all of +the available logs are displayed for that service. If specified with the +`-n` flag then only the most recent `` lines from that service are +displayed. + +An error will be returned if a specified service does not exist. + +## OPTIONS + +`-d`, `--dir` +Path containing a .flox/ directory. + +`--follow` +Follow log output for the specified services. Required when no service +names are supplied. + +`-n`, `--tail` +Display only the last `` lines from the logs of the specified +services. + +`` +Which service(s) to display logs for. When omitted logs from all +services will be displayed but the `--follow` flag is required. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## EXAMPLES: + +Follow logs for all services: + + $ flox services logs --follow + service1: hello + service2: hello + ... + +Follow logs for a subset of services: + + $ flox services logs --follow service1 service3 + service1: hello + service3: hello + ... + +Display all available logs for a single service: + + $ flox services logs myservice + starting... + running... + stopping... + completed + +## SEE ALSO + +[`flox-activate(1)`](./flox-activate.md) +[`flox-services-start(1)`](./flox-services-start.md) diff --git a/docs/reference/command-reference/flox-services-restart.md b/docs/reference/command-reference/flox-services-restart.md new file mode 100644 index 00000000..524b046e --- /dev/null +++ b/docs/reference/command-reference/flox-services-restart.md @@ -0,0 +1,91 @@ +--- +title: flox services restart +description: Command reference for the `flox services restart` command. +--- + +# `flox services restart` command + +## NAME + +flox-services-restart - restart running services + +## SYNOPSIS + + flox [] services restart + [-d= | -r=] + [] ... + +## DESCRIPTION + +Restarts the specified services. + +If no services are specified, stops all running services and starts new +services using the latest build of the environment. If one or more +services are running, then the specified services are started using the +service config that the running services were started with. + +If one or more services are running, the specified services will be +started using the service config that the running services were started +with. + +When all services are restarted, they are started from an ephemeral +activation that uses the latest build of the environment. This may not +be the build of the environment that your shell has activated, so the +environment variables present for services may be different from the +ones in your shell. To ensure that your shell and the services have the +same environment, reactivate your environment after making edits to the +manifest. + +An error is displayed if the specified service does not exist. + +## OPTIONS + +`-d`, `--dir` +Path containing a .flox/ directory. + +`` +The name(s) of the services to restart. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## EXAMPLES: + +Restart a single service: + + $ flox services restart myservice + ✅ Service 'myservice' restarted. + +Restart all services: + + $ flox services restart + ✅ Service 'service1' restarted. + ✅ Service 'service2' restarted. + ✅ Service 'service3' restarted. + +## SEE ALSO + +[`flox-activate(1)`](./flox-activate.md) diff --git a/docs/reference/command-reference/flox-services-start.md b/docs/reference/command-reference/flox-services-start.md new file mode 100644 index 00000000..c91fcfa4 --- /dev/null +++ b/docs/reference/command-reference/flox-services-start.md @@ -0,0 +1,96 @@ +--- +title: flox services start +description: Command reference for the `flox services start` command. +--- + +# `flox services start` command + +## NAME + +flox-services-start - start services + +## SYNOPSIS + + flox [] services start + [-d= | -r=] + [] ... + +## DESCRIPTION + +Starts the specified services. + +If any services are currently running, a warning will be displayed for +each specified service that is already running but the command will +still succeed. If a specified service does not exist, an error will +displayed and no services will be started. + +If no services are currently running, then the services will be started +from an ephemeral activation in order to use the most recent build of +the environment. This may be different from the build of the environment +that the current shell has activated, so the services and your shell may +have different environment variables or values. To ensure that your +shell and the services have the same environment, reactivate your +environment after making edits to the manifest. + +A remote environment can only have a single set of running services, +regardless of how many times the environment is activated concurrently. + +## OPTIONS + +`-d`, `--dir` +Path containing a .flox/ directory. + +`` +The name(s) of the services to start. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## EXAMPLES: + +Start a service named ‘server’: + + $ flox services start server + +Start all services: + + $ flox services start + +Attempt to start a service that doesn’t exist: + + $ flox services start myservice doesnt_exist + ❌ ERROR: Service 'doesnt_exist' not found. + +Attempt to start a service that is already running: + + $ flox services start running not_running + ✅ Service 'not_running' started + ⚠️ Service 'running' is already running + +## SEE ALSO + +[`flox-activate(1)`](./flox-activate.md) +[`flox-services-stop(1)`](./flox-services-stop.md) diff --git a/docs/reference/command-reference/flox-services-status.md b/docs/reference/command-reference/flox-services-status.md new file mode 100644 index 00000000..f90078f5 --- /dev/null +++ b/docs/reference/command-reference/flox-services-status.md @@ -0,0 +1,81 @@ +--- +title: flox services status +description: Command reference for the `flox services status` command. +--- + +# `flox services status` command + +## NAME + +flox-services-status - display the status of services + +## SYNOPSIS + + flox [] services status + [-d= | -r=] + [--json] + [] ... + +## DESCRIPTION + +Displays the status of one or more services. + +If no services are specified, then all services will be displayed. If no +services have been started for this environment, an error will be +displayed. An error will also be displayed if one of the specified +services does not exist. + +## OPTIONS + +`-d`, `--dir` +Path containing a .flox/ directory. + +`--json` +Print statuses formatted as JSON. Each service is printed as a single +JSON object on its own line. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## EXAMPLES: + +Display statuses for all services: + + $ flox services status + NAME STATUS PID + sleeping Running 89718 + myservice Running 12345 + +Display the status of a single service: + + $ flox services status myservice + NAME STATUS PID + myservice Running 12345 + +## SEE ALSO + +[`flox-activate(1)`](./flox-activate.md) +[`flox-services-start(1)`](./flox-services-start.md) diff --git a/docs/reference/command-reference/flox-services-stop.md b/docs/reference/command-reference/flox-services-stop.md new file mode 100644 index 00000000..26a77ccb --- /dev/null +++ b/docs/reference/command-reference/flox-services-stop.md @@ -0,0 +1,89 @@ +--- +title: flox services stop +description: Command reference for the `flox services stop` command. +--- + +# `flox services stop` command + +## NAME + +flox-services-stop - stop running services + +## SYNOPSIS + + flox [] services stop + [-d= | -r=] + [] ... + +## DESCRIPTION + +Stops the specified running services. + +If no services are specified, then all services will be stopped. If any +of the specified services are not currently running, a warning will be +displayed and the remaining services will be stopped. + +If any of the specified services do not exist, an error will be returned +and no services will be stopped. If an error is encountered while +stopping one of the specified services, the remaining services will +still be stopped a warning will be displayed for the services that +failed to stop, and a non-zero exit code will be returned. + +## OPTIONS + +`-d`, `--dir` +Path containing a .flox/ directory. + +`` +The name(s) of the services to stop. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## EXAMPLES: + +Stop a running service named ‘server’: + + $ flox services stop server + +Stop all running services: + + $ flox services stop + +Attempt to stop a service that doesn’t exist: + + $ flox services stop myservice doesnt_exist + ❌ ERROR: Service 'doesnt_exist' not found. + +Attempt to stop a service that isn’t running: + + $ flox services stop running not_running + ⚠️ Service 'not_running' is not running + ✅ Service 'running' stopped + +## SEE ALSO + +[`flox-activate(1)`](./flox-activate.md) diff --git a/docs/reference/command-reference/flox-show.md b/docs/reference/command-reference/flox-show.md new file mode 100644 index 00000000..e057a6cf --- /dev/null +++ b/docs/reference/command-reference/flox-show.md @@ -0,0 +1,72 @@ +--- +title: flox show +description: Command reference for the `flox show` command. +--- + +# `flox show` command + +## NAME + +flox-show - show detailed information about a single package + +## SYNOPSIS + + flox [] show + +## DESCRIPTION + +Show detailed information about a single package. + +The default output includes the package description, name, and version. + +### Package names + +Packages are organized in a hierarchical structure such that certain +packages are found at the top level (e.g. `ripgrep`), and other packages +are found under package sets (e.g. `python310Packages.pip`). We call +this location within the catalog the “pkg-path”. + +The pkg-path is searched when you execute a `flox search` command. The +pkg-path is what’s shown by `flox show`. Finally, the pkg-path appears +in your manifest after a `flox install`. + +``` toml +[install] +ripgrep.pkg-path = "ripgrep" +pip.pkg-path = "python310Packages.pip" +``` + +## OPTIONS + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +### Show Options + +`` +Package name to show details for. + +## EXAMPLES: + +Display detailed information about the `ripgrep` package: + + $ flox show ripgrep + ripgrep - A utility that combines the usability of The Silver Searcher with the raw speed of grep + ripgrep@13.0.0 + ripgrep@14.1.0 + +## SEE ALSO + +[`flox-search(1)`](./flox-search.md), +[`flox-install(1)`](./flox-install.md) diff --git a/docs/reference/command-reference/flox-uninstall.md b/docs/reference/command-reference/flox-uninstall.md new file mode 100644 index 00000000..6555b0a7 --- /dev/null +++ b/docs/reference/command-reference/flox-uninstall.md @@ -0,0 +1,67 @@ +--- +title: flox uninstall +description: Command reference for the `flox uninstall` command. +--- + +# `flox uninstall` command + +## NAME + +flox-uninstall - remove packages from an environment + +## SYNOPSIS + + flox [] (uninstall|rm) + [-d= | -r=] + + +## DESCRIPTION + +Uninstall packages from an environment. + +Just like package installation, package uninstallation is transactional. +See [`flox-install(1)`](./flox-install.md) for more details on +transactions. Requesting to uninstall multiple packages where at least +one of them was not previously installed will cause the transaction to +fail and no packages will be uninstalled. + +## OPTIONS + +### Remove Options + +`` +The install IDs or package paths of the packages to remove. If the +manifest contains both an install ID and a package with matching package +path, the install ID takes precedence. If the same package path is +installed under different install IDs, an error is returned. A package +path can optionally contain the original version constraint. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-install(1)`](./flox-install.md) diff --git a/docs/reference/command-reference/flox-update.md b/docs/reference/command-reference/flox-update.md new file mode 100644 index 00000000..e5e813d7 --- /dev/null +++ b/docs/reference/command-reference/flox-update.md @@ -0,0 +1,79 @@ +--- +title: flox update +description: Command reference for the `flox update` command. +--- + +# `flox update` command + +> **Warning:** This command is **deprecated** and no longer supported + +## NAME + +flox-update - update the global base catalog or an environment’s base +catalog + +## SYNOPSIS + + flox [] update + [--global | (-d= | -r=/)] + +## DESCRIPTION + +Update an environment’s base catalog, or update the global base catalog +if `--global` is specified. + +The base catalog is a collection of packages used by various flox +subcommands. + +The global base catalog provides packages for +[`flox-search(1)`](./flox-search.md) and +[`flox-show(1)`](./flox-show.md) when not using an environment, and it +is used to initialize an environment’s base catalog. + +An environment’s base catalog provides packages for +[`flox-search(1)`](./flox-search.md) and +[`flox-show(1)`](./flox-show.md) when using that environment, and it +provides packages for [`flox-install(1)`](./flox-install.md) and +[`flox-upgrade(1)`](./flox-upgrade.md). + +Note that updating an environment’s base catalog and upgrading packages +are two separate options. Upgrading packages will usually require +running an update command followed by a +[`flox-upgrade`](./flox-upgrade.md). + +## OPTIONS + +### Update Options + +`--global` +Update the global base catalog + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-upgrade(1)`](./flox-upgrade.md) diff --git a/docs/reference/command-reference/flox-upgrade.md b/docs/reference/command-reference/flox-upgrade.md new file mode 100644 index 00000000..5251cf21 --- /dev/null +++ b/docs/reference/command-reference/flox-upgrade.md @@ -0,0 +1,73 @@ +--- +title: flox upgrade +description: Command reference for the `flox upgrade` command. +--- + +# `flox upgrade` command + +## NAME + +flox-upgrade - upgrade packages in an environment + +## SYNOPSIS + + flox [] upgrade + [-d= | -r=/] + []... + +## DESCRIPTION + +Upgrade packages in an environment to versions present in the catalog. + +When no arguments are specified, all packages in the environment are +upgraded. + +Packages to upgrade can be specified by either pkg-group name, or by ID. +If the specified argument is both a pkg-group name and an install ID, +both the package with the install ID and packages belonging to the +pkg-group are upgraded. + +Packages without a specified pkg-group in the manifest are placed in a +pkg-group named ‘toplevel’. The packages in that pkg-group can be +upgraded without updating any other pkg-groups by passing ‘toplevel’ as +the pkg-group name. + +See [`manifest.toml(5)`](./manifest.toml.md) for more on using +pkg-groups. + +## OPTIONS + +### Upgrade Options + +`` +Install ID or pkg-group to upgrade. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`manifest.toml(5)`](./manifest.toml.md) diff --git a/docs/reference/command-reference/flox.md b/docs/reference/command-reference/flox.md new file mode 100644 index 00000000..991348e1 --- /dev/null +++ b/docs/reference/command-reference/flox.md @@ -0,0 +1,141 @@ +--- +title: flox +description: Command reference for the `flox` command. +--- + +# `flox` command + +## NAME + +flox - developer environments you can take with you + +## SYNOPSIS + + flox [] + [] + [] ... + +## DESCRIPTION + +Flox is a virtual environment and package manager all in one. + +With flox you create environments that layer and provide dependencies +just where it matters, making them portable across the full software +lifecycle. + +### Command Line Completions + +Flox ships with command line completions for `bash`, `fish` and `zsh`. +These completions are installed alongside Flox. + +## OPTIONS + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +### flox Options + +`--version` +Print `flox` version. + +## COMMANDS + +Flox commands are grouped into categories pertaining to local +development, sharing environments, and administration. + +### Local Development Commands + +`init` +Create an environment in the current directory. + +`activate` +Enter the environment, type `exit` to leave. + +`search` +Search for system or library packages to install. + +`show` +Show details about a single package. + +`install`, `i` +Install packages into an environment. + +`uninstall` +Uninstall installed packages from an environment. + +`edit` +Edit the declarative environment configuration file. + +`list`, ‘l’ +List packages installed in an environment. + +`delete` +Delete an environment. + +### Sharing Commands + +`push` +Send an environment to FloxHub. + +`pull` +Pull an environment from FloxHub. + +### Additional Commands + +`update` +Update an environment’s base catalog or update the global base catalog. + +`upgrade` +Upgrade packages in an environment. + +`config` +View and set configuration options. + +`auth` +FloxHub authentication commands. + +## ENVIRONMENT VARIABLES + +`$FLOX_DISABLE_METRICS` +Variable for disabling the collection/sending of metrics data. If set to +`true`, prevents Flox from submitting basic metrics information such as +a unique token and the subcommand issued. + +`$EDITOR`, `$VISUAL` +Override the default editor used for editing environment manifests and +commit messages. + +`$SSL_CERT_FILE`, `$NIX_SSL_CERT_FILE` +If set, overrides the path to the default flox-provided SSL certificate +bundle. Set `NIX_SSL_CERT_FILE` to only override packages built with +Nix, and otherwise set `SSL_CERT_FILE` to override the value for all +packages. + +See also: [Nix environment variables - +`NIX_SSL_CERT_FILE`](https://nixos.org/manual/nix/stable/installation/env-variables.html#nix_ssl_cert_file) + +## SEE ALSO + +[`flox-init`(1)](./flox-init.md), +[`flox-activate`(1)](./flox-activate.md), +[`flox-install`(1)](./flox-install.md), +[`flox-uninstall(1)`](./flox-uninstall.md), +[`flox-upgrade`(1)](./flox-upgrade.md), +[`flox-search`(1)](./flox-search.md), [`flox-show(1)`](./flox-show.md), +[`flox-edit`(1)](./flox-edit.md), +[`manifest-toml`(5)](./manifest.toml.md), +[`flox-list`(1)](./flox-list.md), [`flox-auth(1)`](./flox-auth.md), +[`flox-push`(1)](./flox-push.md), [`flox-pull`(1)](./flox-pull.md), +[`flox-delete`(1)](./flox-delete.md), +[`flox-config`(1)](./flox-config.md) diff --git a/docs/reference/command-reference/manifest.toml.md b/docs/reference/command-reference/manifest.toml.md new file mode 100644 index 00000000..5b56f316 --- /dev/null +++ b/docs/reference/command-reference/manifest.toml.md @@ -0,0 +1,475 @@ +--- +title: manifest.toml +description: Reference for the manifest.toml format. +--- + +# `manifest.toml` + +## NAME + +manifest.toml - declarative environment configuration format + +## SYNOPSIS + +The `manifest.toml` file is a declarative format for specifying the +packages installed in an environment, environment variables to make +available to the environment, a shell script to run upon activation of +the environment, and other options to change the behavior of the +environment. + +## DESCRIPTION + +Flox environments come with a declarative manifest in [TOML +format](https://toml.io/en/v1.0.0). An environment can be defined +entirely by this one file. The file is divided into just a few sections +that are represented as TOML tables: + +- [`[install]`](#install) +- [`[vars]`](#vars) +- [`[hook]`](#hook) +- [`[profile]`](#profile) +- [`[services]`](#services) +- [`[options]`](#options) + +### `[install]` + +The `[install]` table is the core of the environment, specifying which +packages you’d like installed in the environment. An example of the +`[install]` table is shown below: + +``` toml +[install] +ripgrep.pkg-path = "ripgrep" +pip.pkg-path = "python310Packages.pip" +``` + +Since this is TOML, equivalent ways of writing this would be + +``` toml +[install] +ripgrep = { pkg-path = "ripgrep" } +pip = { pkg-path = "python310Packages.pip" } +``` + +or + + [install.ripgrep] + pkg-path = "ripgrep" + + [install.pip] + pkg-path = "python310Packages.pip" + +Flox will use the first format by default when automatically editing the +manifest. + +#### Package names + + + +Packages are organized in a hierarchical structure such that certain +packages are found at the top level (e.g. `ripgrep`), and other packages +are found under package sets (e.g. `python310Packages.pip`). We call +this location within the catalog the “pkg-path”. + +The pkg-path is searched when you execute a `flox search` command. The +pkg-path is what’s shown by `flox show`. Finally, the pkg-path appears +in your manifest after a `flox install`. + +``` toml +[install] +ripgrep.pkg-path = "ripgrep" +pip.pkg-path = "python310Packages.pip" +``` + +#### Package descriptors + +Each entry in the `[install]` table is a key-value pair. The key in the +key-value pair (e.g. `ripgrep`, `pip`) is referred to as an “install +ID”, and represents the name by which you will refer to a particular +package e.g. if you wanted to uninstall or upgrade the package. Install +IDs are inferred from the last attribute in the pkg-path, but may also +be specified either at install-time via the `-i` option or interactively +via [`flox-edit(1)`](./flox-edit.md). + +The value in the key-value pair is called a “package descriptor”. A +package is specified by a number of available options which are separate +from the install ID, so you are free to change them independently of one +another. This allows you to change package details while keeping a +stable install ID, for example upgrading from `gcc.pkg-path = "gcc12"` +to `gcc.pkg-path = "gcc13"`. + +Most package descriptors will be catalog descriptors, which allow +specifying packages from the Flox catalog. A second format, flake +descriptors, is also supported, which allows specifying software to +install from an arbitrary Nix flake. + +##### Catalog descriptors + +The full list of catalog descriptor options is: + + Descriptor ::= { + pkg-group = null | + , version = null | + , systems = null | [, ...] + , pkg-path = + , priority = null | + } + +Only `pkg-path` is required. + +By specifying some of these options you create a set of requirements +that the installed program must satisfy, otherwise installation will +fail. + +By default, all packages belong to the same `pkg-group`, which means +providing specific versions for two different packages can quickly lead +to installation failures. To avoid such failures, either give a looser +`version` constraint, or move one of the packages to a different package +group. + +Each option is described below: + +`pkg-group` +Marks a package as belonging to a pkg-group. + +The pkg-group is a collection of software that is known to work together +at a point in time. Adding packages to a pkg-group enables packages in +the pkg-group to share the same libraries and dependencies, which +ensures maximum compatibility and minimizes the size of the environment. + +Packages are marked as belonging to a pkg-group simply by setting this +option to the name of the pkg-group. Packages that do not have a +pkg-group specified belong to the same group. + +Multiple pkg-groups may resolve to the same version of the catalog. +Pkg-groups are upgraded as a unit, ensuring that the packages within the +pkg-group continue to work together. See +[`flox-upgrade(1)`](./flox-upgrade.md) for more details on how +pkg-groups and packages interact during upgrades. + +`version` +Requires that the package match either an exact version or a semver +range. + +The semantic version can be specified with the typical qualifiers such +as `^`, `>=`, etc. Semantic versions that do not specify all three +fields (`MAJOR.MINOR.PATCH`) will treat the unspecified fields as +wildcards. This instructs Flox to find the latest versions for those +fields. For example `version = "1.2"` would select the latest version in +the `1.2.X` series. + +`systems` +A list of systems on which to install this package. When omitted this +defaults to the same systems that the manifest specifies that it +supports via `options.systems`. + +`pkg-path` +The abbreviated location of a package within a catalog. A pkg-path is a +sequence of one or more attributes joined by a delimiter. For example, +both `ripgrep` and `python310Packages.pip` are pkg-paths. A pkg-path +that contains more than one attribute can be represented as either a +single string that contains a ‘.’-delimited sequence of the attributes, +or it can be represented as a TOML array of strings where each string is +an attribute. For example, both `"python310Packages.pip"` and +`["python310Packages", "pip"]` are equivalent for the `pkg-path` option. + +This option is mutually exclusive with `abs-path`. + +`priority` +A priority used to resolve file conflicts where lower values indicate +higher priority. + +Each package internally has `/bin`, `/man`, `/include`, and other +directories for the files they provide. These directories from all +packages in the environment are merged when building the environment. +Two packages that provide the same `/bin/foo` file cause a conflict, and +it’s ambiguous which file should ultimately be placed into the +environment. Such conflicts can be resolved by assigning different +priorities to the conflicting packages. + +The default priority is 5. Packages with a lower `priority` value will +take precedence over packages with higher `priority` values. + +##### Flake descriptors + +Flake descriptors allow installing software from an arbitrary Nix flake. + +The full list of flake descriptor options is: + + Descriptor ::= { + flake = + , systems = null | [, ...] + , priority = null | + } + +Only `flake` is required. `systems` and `priority` behave the same as +described above for catalog descriptors, and `flake` is described below: + +`flake` +Specifies a Nix flake installable, which Nix refers to as a flake output +attribute and documents at +https://nix.dev/manual/nix/2.17/command-ref/new-cli/nix#flake-output-attribute. +Flake installables are of the form `flakeref[#attrpath]`, where flakeref +is a flake reference and attrpath is an optional attribute path. + +Flox tries to use the same fallback behavior as Nix; if no attrpath is +specified, the flake is checked for containing +`packages.$system.default` or `defaultPackage.$system`. If an attrpath +is specified, it is checked whether `packages.$system.$attrpath` or +`legacyPackages.$system.$attrpath` exist. + +### `[vars]` + +The `[vars]` section allows you to define environment variables for your +environment that are set during environment activation. The environment +variables specified here cannot reference one another. The names and +values of the environment variables are copied verbatim into the +activation script, so capitalization will be preserved. + +Example: + +``` toml +[vars] +DB_URL = "http://localhost:2000" +SERVER_PORT = "3000" +``` + +### `[hook]` + +The `on-activate` script in the `[hook]` section is useful for +performing initialization in a predictable Bash shell environment. + +#### `on-activate` + +The `on-activate` script is sourced from a **bash** shell, and it can be +useful for spawning processes, dynamically setting environment +variables, and creating files and directories to be used by the +subsequent profile scripts, commands, and shells. + +Hook scripts inherit environment variables set in the `[vars]` section, +and variables set here will in turn be inherited by the `[profile]` +scripts described below. + +Any output written to `stdout` in a hook script is redirected to +`stderr` to avoid it being mixed with the output of profile section +scripts that write to `stdout` for “in-place” activations. + +``` toml +[hook] +on-activate = """ + # Interact with the tty as you would in any script + echo "Starting up $FLOX_ENV_DESCRIPTION environment ..." + read -e -p "Favourite colour or favorite color? " value + + # Set variables, create files and directories + venv_dir="$(mktemp -d)" + export venv_dir + + # Perform initialization steps, e.g. create a python venv + python -m venv "$venv_dir" + + # Invoke apps that configure the environment via stdout + eval "$(ssh-agent)" +""" +``` + +The `on-activate` script is not re-run when activations are nested. A +nested activation can occur when an environment is already active and +either `eval "$(flox activate)"` or `flox activate -- CMD` is run. In +this scenario, `on-activate` is not re-run. Currently, environment +variables set by the first run of the `on-activate` script are captured +and then later set by the nested activation, but this behavior may +change. + +The `on-activate` script may be re-run by other commands; we may create +ephemeral activations and thus run the script multiple times for +commands such as `services start`. For this reason, it’s best practice +to make `on-activate` idempotent. However, the environment of your +current shell is only affected by the initial run of the script for the +first activation for your shell. + +It’s also best practice to write hooks defensively, assuming the user is +using the environment from any directory on their machine. + +#### `script` - DEPRECATED + +This field was deprecated in favor of the `profile` section. + +### `[profile]` + +Scripts defined in the `[profile]` section are sourced by *your shell* +and inherit environment variables set in the `[vars]` section and by the +`[hook]` scripts. The `profile.common` script is sourced for every +shell, and special care should be taken to ensure compatibility with all +shells, after which exactly one of `profile.{bash,fish,tcsh,zsh}` is +sourced by the corresponding shell. + +These scripts are useful for performing shell-specific customizations +such as setting aliases or configuring the prompt. + +``` toml +[profile] +common = """ + echo "it's gettin' flox in here" +""" +bash = """ + source $venv_dir/bin/activate + alias foo="echo bar" + set -o vi +""" +zsh = """ + source $venv_dir/bin/activate + alias foo="echo bar" + bindkey -v +""" +fish = """ + source $venv_dir/bin/activate.fish + alias foo="echo bar" + fish_vi_key_bindings +""" +``` + +Profile scripts are re-run for nested activations. A nested activation +can occur when an environment is already active and either +`eval "$(flox activate)"` or `flox activate -- CMD` is run. In this +scenario, profile scripts are run a second time. Re-running profile +scripts allows aliases to be set in subshells that inherit from a parent +shell with an already active environment. + +### `[services]` + +The `[services]` section of the manifest allows you to describe the +services you would like to run as part of your environment e.g. a web +server or a database. The services you define here use the packages +provided by the `[install]` section and any variables you’ve defined in +the `[vars]` section or `hook.on-activate` script. + +The `[services]` section is a table of key-value pairs where the keys +determine the service names, and the values (service descriptors) +determine how to configure and run the services. + +An example service definition is shown below: + +``` toml +[services.database] +command = "postgres start" +vars.PGUSER = "myuser" +vars.PGPASSWORD = "super-secret" +vars.PGDATABASE = "mydb" +vars.PGPORT = "9001" +``` + +This would define a service called `database` that configures and starts +a PostgreSQL database. + +The full set of options is show below: + + ServiceDescriptor ::= { + command = STRING + , vars = null | Map[STRING, STRING] + , is-daemon = null | BOOL + , shutdown = null | Shutdown + , systems = null | [, ...] + } + + Shutdown ::= { + command = STRING + } + +`command` +The command to run (interpreted by a Bash shell) to start the service. +This command can use any environment variables that were set in the +`[vars]` section, the `hook.on-activate` script, or the service-specific +`vars` table. + +`vars` +A table of environment variables to set for the invocation of this +specific service. Nothing outside of this service will observe these +environment variables. + +`is-daemon` +Whether this service spawns a daemon when it starts. Some commands start +a background process and then terminate instead of themselves running +for an extended period of time. These programs need special handling +when it comes time to shut down the services, so you must mark them with +the `is-daemon` field. If this field is set to `true` you must also +specify the `shutdown.command` field, otherwise the process will +continue to run after calling `flox services stop` or after exiting the +last activation of the environment. + +`shutdown.command` +A command to run to shut down the service instead of delivering the +SIGTERM signal to the process. Some programs require special handling to +shut down properly e.g. a program that spawns a server process and uses +a client to tell the server to shut down. Sending a SIGTERM to a client +in that case may not shut down the server. In those cases you may +provide a specific shutdown command to run instead of relying on the +default behavior of sending a SIGTERM to the service. This field is +required if the `is-daemon` field is `true`. + +`systems` +An optional list of systems on which to run this service. If omitted, +the service is not restricted. + +### `[options]` + +The `[options]` section of the manifest details settings for the +environment itself. + +The full set of options are listed below: + + Options ::= { + systems = null | [, ...] + , allow = null | Allows + , semver = null | Semver + , cuda-detection = null | + } + + Allows ::= { + unfree = null | + , broken = null | + , licenses = null | [, ...] + } + + Semver ::= { + allow-pre-releases = + } + +`systems` +The allowlist of systems that this environment supports. Valid values +are `x86_64-linux`, `aarch64-linux`, `x86_64-darwin`, and +`aarch64-darwin`. [`flox init`](./flox-init.md) automatically populates +this list with the current system type. A user that attempts to pull an +environment from FloxHub when their environment isn’t explicitly +supported will be prompted whether to automatically add their system to +this list. See [`flox-pull(1)`](./flox-pull.md) for more details. + +`allow.unfree` +Allows packages with unfree licenses to be installed and appear in +search results. The default is `false`. + +`allow.broken` +Allows packages that are marked `broken` in the catalog to be installed +and appear in search results. The default is `false`. + +`allow.licenses` +An allowlist of software licenses to allow in search results in +installs. Valid entries are [SPDX +Identifiers](https://spdx.org/licenses). + +`semver.allow-pre-releases` +Whether to allow pre-release software for package installations. The +default is `false`. Setting this value to `true` would allow a package +version `4.2.0-pre` rather than `4.1.9`. + +`cuda-detection` +Whether to detect CUDA libraries and provide them to the environment. +The default is `true`. When enabled, Flox will detect if you have an +Nvidia device and attempt to locate `libcuda` in well-known paths. Then +it will symlink the libraries into `.flox/lib` and add that path to +`FLOX_ENV_LIB_DIRS`. + +## SEE ALSO + +[`flox-init(1)`](./flox-init.md), +[`flox-install(1)`](./flox-install.md), [`flox-edit(1)`](./flox-edit.md) diff --git a/justfile b/justfile new file mode 100644 index 00000000..47e95814 --- /dev/null +++ b/justfile @@ -0,0 +1,28 @@ +# Flox Documentation +# Run `just` to see available recipes + +# Show available recipes +default: + @just --list + +# Start development server with live reload +dev: + @echo "Starting development server..." + @echo "Site will be available at: http://127.0.0.1:8000" + @echo "Press Ctrl+C to stop" + mkdocs serve + +# Build static site and generate AI files +build: + @echo "Building static site..." + mkdocs build + @echo "Generating AI files..." + python3 tools/generate_llms_txt.py ./site + @echo "Build complete! Site available in ./site/" + +# Clean build artifacts +clean: + @echo "Cleaning build artifacts..." + rm -rf site/ + rm -rf public/ + @echo "Clean complete!" From 04d16115238b7bb71f891dfc4f146855008d90c3 Mon Sep 17 00:00:00 2001 From: Bill LeVine Date: Fri, 10 Apr 2026 11:44:27 -0400 Subject: [PATCH 05/14] chore(ci): remove redundant explicit llms file copies cp -R ./site/* already covers llms.txt and llms-full.txt Co-authored-by: Claude Sonnet 4.6 (1M context) --- .github/workflows/ci.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 62241bc3..42a22a28 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -50,8 +50,6 @@ jobs: python3 tools/generate_llms_txt.py ./site mkdir -p ./public/docs cp -R ./site/* ./public/docs/ - cp ./site/llms.txt ./public/docs/llms.txt - cp ./site/llms-full.txt ./public/docs/llms-full.txt chmod -R +w ./public/docs cp netlify.toml ./public/ From d0f62271c05002cb915877ae814f24f16bd4041a Mon Sep 17 00:00:00 2001 From: Bill LeVine Date: Fri, 10 Apr 2026 11:54:40 -0400 Subject: [PATCH 06/14] chore: remove auto-generated reference docs (unrelated to this PR) These files were accidentally swept in via git add -A. They belong in a separate commit once lint issues are resolved. Co-authored-by: Claude Sonnet 4.6 (1M context) --- docs/reference/command-reference/README.md | 12 - .../command-reference/flox-activate.md | 204 -------- docs/reference/command-reference/flox-auth.md | 44 -- .../command-reference/flox-config.md | 134 ----- .../command-reference/flox-containerize.md | 105 ---- .../command-reference/flox-delete.md | 66 --- docs/reference/command-reference/flox-edit.md | 105 ---- docs/reference/command-reference/flox-envs.md | 59 --- docs/reference/command-reference/flox-init.md | 73 --- .../command-reference/flox-install.md | 121 ----- docs/reference/command-reference/flox-list.md | 67 --- docs/reference/command-reference/flox-pull.md | 84 ---- docs/reference/command-reference/flox-push.md | 73 --- .../command-reference/flox-search.md | 82 --- .../command-reference/flox-services-logs.md | 107 ---- .../flox-services-restart.md | 91 ---- .../command-reference/flox-services-start.md | 96 ---- .../command-reference/flox-services-status.md | 81 --- .../command-reference/flox-services-stop.md | 89 ---- docs/reference/command-reference/flox-show.md | 72 --- .../command-reference/flox-uninstall.md | 67 --- .../command-reference/flox-update.md | 79 --- .../command-reference/flox-upgrade.md | 73 --- docs/reference/command-reference/flox.md | 141 ------ .../command-reference/manifest.toml.md | 475 ------------------ 25 files changed, 2600 deletions(-) delete mode 100644 docs/reference/command-reference/README.md delete mode 100644 docs/reference/command-reference/flox-activate.md delete mode 100644 docs/reference/command-reference/flox-auth.md delete mode 100644 docs/reference/command-reference/flox-config.md delete mode 100644 docs/reference/command-reference/flox-containerize.md delete mode 100644 docs/reference/command-reference/flox-delete.md delete mode 100644 docs/reference/command-reference/flox-edit.md delete mode 100644 docs/reference/command-reference/flox-envs.md delete mode 100644 docs/reference/command-reference/flox-init.md delete mode 100644 docs/reference/command-reference/flox-install.md delete mode 100644 docs/reference/command-reference/flox-list.md delete mode 100644 docs/reference/command-reference/flox-pull.md delete mode 100644 docs/reference/command-reference/flox-push.md delete mode 100644 docs/reference/command-reference/flox-search.md delete mode 100644 docs/reference/command-reference/flox-services-logs.md delete mode 100644 docs/reference/command-reference/flox-services-restart.md delete mode 100644 docs/reference/command-reference/flox-services-start.md delete mode 100644 docs/reference/command-reference/flox-services-status.md delete mode 100644 docs/reference/command-reference/flox-services-stop.md delete mode 100644 docs/reference/command-reference/flox-show.md delete mode 100644 docs/reference/command-reference/flox-uninstall.md delete mode 100644 docs/reference/command-reference/flox-update.md delete mode 100644 docs/reference/command-reference/flox-upgrade.md delete mode 100644 docs/reference/command-reference/flox.md delete mode 100644 docs/reference/command-reference/manifest.toml.md diff --git a/docs/reference/command-reference/README.md b/docs/reference/command-reference/README.md deleted file mode 100644 index 843785de..00000000 --- a/docs/reference/command-reference/README.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: README -description: Command reference for the `README` command. ---- - -# `README` command ---- -title: README -description: Command reference for the `README` command. ---- - -# `README` command diff --git a/docs/reference/command-reference/flox-activate.md b/docs/reference/command-reference/flox-activate.md deleted file mode 100644 index a6d86dee..00000000 --- a/docs/reference/command-reference/flox-activate.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -title: flox activate -description: Command reference for the `flox activate` command. ---- - -# `flox activate` command - -## NAME - -flox-activate - activate environments - -## SYNOPSIS - - flox [] activate - [-d= | -r=/] - [-t] - [--print-script] - [-- []] - -## DESCRIPTION - -Sets environment variables and aliases, runs hooks, starts services, and -adds `bin` directories to your `$PATH`. - -`flox activate` may run in one of three modes: - -- interactive: `flox activate` when invoked from an interactive shell - Launches an interactive sub-shell. The shell to be launched is - determined by `$FLOX_SHELL` or `$SHELL`. -- command: `flox activate -- CMD` - Executes `CMD` in the same environment as if run inside an interactive - shell produced by an interactive `flox activate` The shell `CMD` is - run by is determined by `$FLOX_SHELL` or `$SHELL`. -- in-place: `flox activate` when invoked from an non-interactive shell - with it’s `stdout` redirected e.g. `eval "$(flox activate)"` - Produces commands to be sourced by the parent shell. Flox will - determine the parent shell from `$FLOX_SHELL` or otherwise - automatically determine the parent shell and fall back to `$SHELL`. - -`flox activate` currently supports `bash`, `fish`, `tcsh`, and `zsh` -shells for any of the detection mechanisms described above. - -When invoked interactively, the shell prompt will be modified to display -the active environments, as shown below: - - flox [env1 env2 env3] - -When multiple environments are activated each of their shell hooks -(`profile` and `hook` scripts) are executed in the context of the -environment that they come from. This means that for each shell hook -various environment variables such as `PATH`, `MANPATH`, -`PKG_CONFIG_PATH`, `PYTHONPATH`, etc, are set to the appropriate values -for the environment in which the shell hook was defined. See -[`manifest.toml(5)`](./manifest.toml.md) for more details on shell -hooks. - -## OPTIONS - -### Activate Options - -`-- []` -Command to run in the environment. Spawns the command in a subshell that -does not leak into the calling process. - -`-t`, `--trust` -Trust a remote environment for this activation. Activating an -environment executes a shell hook which may execute arbitrary code. This -presents a security risk, so you will be prompted whether to trust the -environment. Environments owned by the current user and Flox are always -trusted. You may set certain environments to always be trusted using the -config key `trusted_environments."" = (trust | deny)`, or -via the following command: -`flox config --set trusted_environments.\"\" trust`. - -`--print-script` -Prints an activation script to `stdout` that’s suitable for sourcing in -a shell rather than activation via creating a subshell. `flox` -automatically knows when to print the activation script to `stdout`, so -this command is just a debugging aid for users. - -`-s`, `--start-services` -Start the services listed in the manifest when activating the -environment. If no services are running, the services from the manifest -will be started, otherwise a warning will displayed and activation will -continue. - -This flag is currently incompatible with “in-place” activations and -remote environments, but these features will be added in the future. - -The services started with this flag will be cleaned up once the last -activation of this environment terminates. - -A remote environment can only have a single set of running services, -regardless of how many times the environment is activated concurrently. - -### Environment Options - -If no environment is specified for an environment command, the -environment in the current directory or the active environment that was -last activated is used. - -`-d`, `--dir` -Path containing a .flox/ directory. - -`-r`, `--remote` -A remote environment on FloxHub, specified in the form `/`. - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## ENVIRONMENT VARIABLES - -### Variables set by `flox activate` - -`$FLOX_ENV` -Contains the path to the built environment. This directory contains a -merged set of `bin`, `lib`, etc directories for all the packages in the -environment. - -`$FLOX_PROMPT_ENVIRONMENTS` -Contains a space-delimited list of the active environments, -e.g. `owner1/foo owner2/bar local_env`. If, `hide_default_prompt` is set -to `true`, environments named `default` are excluded. - -`$FLOX_ENV_CACHE` -`activate` sets this variable to a directory that can be used by an -environment’s hook to store transient files. These files will persist -for environments used locally, but they will not be pushed, and they -will not persist when using a remote environment with `-r`. - -`$FLOX_ENV_PROJECT` -`activate` sets this variable to the directory of the project using the -flox environment. For environments stored locally, this is the directory -containing the environment. When running `flox activate -r`, this is set -to the current working directory. This variable can be used to find -project files in environment hooks. - -`$_FLOX_ACTIVE_ENVIRONMENTS` -A JSON array containing one object per active environment. This is -currently an implementation detail and its contents are subject to -change. - -`$FLOX_ACTIVATE_START_SERVICES` -`"true"` if this activation started services, `"false"` otherwise. - -### Variables used by `flox activate` - -`$FLOX_SHELL` -When launching an interactive sub-shell, Flox launches the shell -specified in `$FLOX_SHELL` if it is set. When printing a shell for -sourcing in the current shell, Flox will produce a script suitable for -`$FLOX_SHELL` if it is set. - -`$SHELL` -When launching an interactive sub-shell, Flox launches the shell -specified in `$SHELL` if it is set and `$FLOX_SHELL` is not set. When -printing a shell for sourcing in the current shell, Flox will produce a -script suitable for `$SHELL` if it is set and `$FLOX_SHELL` is not set -and Flox can’t detect the parent shell. - -`$FLOX_PROMPT_COLOR_{1,2}` -Flox adds text to the beginning of the shell prompt to indicate which -environments are active. A set of default colors are used to color this -prompt, but the colors may be overridden with the `$FLOX_PROMPT_COLOR_1` -and `$FLOX_PROMPT_COLOR_2` environment variables. - -The values of these variables should be integers chosen from the -256-color palette as described in the [xterm-256color -chart](https://upload.wikimedia.org/wikipedia/commons/1/15/Xterm_256color_chart.svg). - -## EXAMPLES: - -Activate an environment stored in the current directory: - - $ flox activate - -Activate an environment `some_user/myenv` that’s been pushed to FloxHub: - - $ flox activate -r some_user/myenv - -Invoke a command inside an environment without entering its subshell: - - $ flox activate -- cmd --some-arg arg1 arg2 - -Activate `default` Flox environment only within the current shell (add -to the relevant “rc” file, e.g. `~/.bashrc` or `~/.zprofile`): - - $ eval "$(flox activate)" - -## SEE ALSO - -[`flox-push(1)`](./flox-push.md), [`flox-pull(1)`](./flox-pull.md), -[`flox-edit(1)`](./flox-edit.md), [`flox-delete(1)`](./flox-delete.md) diff --git a/docs/reference/command-reference/flox-auth.md b/docs/reference/command-reference/flox-auth.md deleted file mode 100644 index b0a8a271..00000000 --- a/docs/reference/command-reference/flox-auth.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: flox auth -description: Command reference for the `flox auth` command. ---- - -# `flox auth` command - -## NAME - -flox-auth - FloxHub authentication commands - -## SYNOPSIS - - flox [] auth - (login | logout | status) - -## DESCRIPTION - -Authenticate with FloxHub so that you can push and pull environments. - -## OPTIONS - -### `login` - -Logs in to FloxHub. - -Required to interact with environments on FloxHub via `flox push`, -`flox pull`, and `flox activate -r`. Authenticating also automatically -trusts your personal environments. - -Prompts you to enter a one-time code at a specified URL. If called -interactively it can open the browser for you if you press ``. - -See also: [`flox-push(1)`](./flox-push.md), -[`flox-pull(1)`](./flox-pull.md), -[`flox-activate(1)`](./flox-activate.md) - -### `logout` - -Logs out from FloxHub. - -### `status` - -Print your current login status diff --git a/docs/reference/command-reference/flox-config.md b/docs/reference/command-reference/flox-config.md deleted file mode 100644 index a26d1c61..00000000 --- a/docs/reference/command-reference/flox-config.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: flox config -description: Command reference for the `flox config` command. ---- - -# `flox config` command - -## NAME - -flox-config - view and set configuration options - -## SYNOPSIS - - flox [] config - [-l | - -r | - --set | - --set-number | - --set-bool | - --delete=] - -## DESCRIPTION - -Without any flags or when `-l` is passed, `flox config` shows all -options with their computed value. - -Config values are read from the following sources in order of descending -priority: - -1. Environment variables. All config options may be set by prefixing - with `FLOX_` and using SCREAMING_SNAKE_CASE. For example, - `disable_metrics` may be set with `FLOX_DISABLE_METRICS=true`. -2. User customizations from `$FLOX_CONFIG_DIR/flox.toml` if set or else - `$XDG_CONFIG_HOME/flox/flox.toml`. -3. User customizations from `flox/flox.toml` in any of - `$XDG_CONFIG_DIRS`. -4. System settings from `/etc/flox.toml`. -5. `flox` provided defaults. - -`flox config` commands that mutate configuration always write to -`${FLOX_CONFIG_DIR:-$XDG_CONFIG_HOME}/flox/flox.toml`. - -### Key Format - -`` supports dot-separated queries for nested values, for example: - - flox config --set 'trusted_environments."owner/name"' trust - -## OPTIONS - -### Config Options - -`-l`, `--list` -List the current values of all options. - -`-r`, `--reset` -Reset all options to their default values without confirmation. - -`--set ` -Set ` = ` for string values - -`--set-number ` -Set ` = ` for number values - -`--set-bool ` -Set ` = ` for boolean values - -`--delete ` -Delete config key - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## SUPPORTED CONFIGURATION OPTIONS - -`config_dir` -Directory where flox should load its configuration file (default: -`$XDG_CONFIG_HOME/flox`). This option will only take effect if set with -`$FLOX_CONFIG_DIR`. `$FLOX_CONFIG_DIR` and `config_dir` are ignored. - -`cache_dir` -Directory where flox should store ephemeral data (default: -`$XDG_CACHE_HOME/flox`). - -`data_dir` -Directory where flox should store persistent data (default: -`$XDG_DATA_HOME/flox`). - -`disable_metrics` -Disable collecting and sending usage metrics. - -`floxhub_token` -Token to authenticate on FloxHub. - -`hide_default_prompt` -Hide environments named ‘default’ from the shell prompt, and don’t add -environments named ‘default’ to `$FLOX_PROMPT_ENVIRONMENTS` (default: -false). - -`search_limit` -How many items `flox search` should show by default. - -`set_prompt` -Set shell prompt when activating an environment (default: true). - -`shell_prompt` - DEPRECATED -Rule whether to change the shell prompt in activated environments -(default: “show-all”). This has been deprecated in favor of `set_prompt` -and `hide_default_prompt`. Possible values are \* “show-all”: shows all -active anvironments \* “hide-all”: disables the modification of the -shell prompt \* “hide-default”: filters out environments named ‘default’ -from the shell prompt - -`trusted_environments` -Remote environments that are trusted for activation. Contains keys of -the form `"/"` that map to either `"trust"` or `"deny"`. - -## ENVIRONMENT VARIABLES - -`$FLOX_DISABLE_METRICS` -Variable for disabling the collection/sending of metrics data. If set to -`true`, prevents Flox from submitting basic metrics information such as -a unique token and the subcommand issued. diff --git a/docs/reference/command-reference/flox-containerize.md b/docs/reference/command-reference/flox-containerize.md deleted file mode 100644 index 58881cd4..00000000 --- a/docs/reference/command-reference/flox-containerize.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: flox containerize -description: Command reference for the `flox containerize` command. ---- - -# `flox containerize` command - -> **Warning:** This command is **experimental** and its behaviour is -> subject to change - -## NAME - -flox-containerize - export an environment as a container image - -## SYNOPSIS - - flox [] containerize - [-d= | -r=] - [-o=] - -## DESCRIPTION - -Export a Flox environment as a container image. The image is written to -``. Then use `docker load -i ` to load the image into -docker. When `` is `-`, the image is written to `stdout`, and can -be piped into `docker load` directly. - -Running the container will behave like running `flox activate`. Running -the container interactively with `docker run -it `, will -launch a bash subshell in the container with all your packages and -variables set after running the activation hook. This is akin to -`flox activate` - -Running the container non-interactively with `docker run ` -allows you to run a command within the container without launching a -subshell, similar to `flox activate --` - -**Note**: The `containerize` command is currently **only available on -Linux**. The produced container however can also run on macOS. - -## OPTIONS - -`-o`, `--output` -Write the container to `` (default: -`./-container.tar`) If `` is `-`, writes to -`stdout`. - -### Environment Options - -If no environment is specified for an environment command, the -environment in the current directory or the active environment that was -last activated is used. - -`-d`, `--dir` -Path containing a .flox/ directory. - -`-r`, `--remote` -A remote environment on FloxHub, specified in the form `/`. - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## EXAMPLES - -Create a container image file and load it into Docker: - - $ flox containerize -o ./mycontainer.tar - $ docker load -i ./mycontainer.tar - -Pipe the image into Docker directly: - - $ flox containerize -o - | docker load - -Run the container interactively: - - $ flox init - $ flox install hello - $ flox containerize -o - | docker load - $ docker run --rm -it - [floxenv] $ hello - Hello, world! - -Run a specific command from within the container, but do not launch a -subshell. - - $ flox init - $ flox install hello - $ flox containerize -o - | docker load - $ docker run hello - Hello, world - -## SEE ALSO - -[`flox-activate(1)`](./flox-activate.md) \[`docker-load(1)`\] diff --git a/docs/reference/command-reference/flox-delete.md b/docs/reference/command-reference/flox-delete.md deleted file mode 100644 index c246351f..00000000 --- a/docs/reference/command-reference/flox-delete.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: flox delete -description: Command reference for the `flox delete` command. ---- - -# `flox delete` command - -## NAME - -flox-delete - delete an environment - -## SYNOPSIS - - flox [] delete - [-f] - [-d=] - -## DESCRIPTION - -Deletes all data pertaining to an environment. By default only the -environment in the current directory is deleted, but environments in -other directories may be deleted via the `-d` flag. - -By default you will be prompted for a confirmation before deleting the -environment. The `-f` flag skips the confirmation dialog and is required -for non-interactive use. - -## OPTIONS - -### Delete Options - -`-f`, `--force` -Delete the environment without confirmation. - - - -### Environment Options - -If no environment is specified for an environment command, the -environment in the current directory or the active environment that was -last activated is used. - -`-d`, `--dir` -Path containing a .flox/ directory. - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## See Also - -[`flox-init(1)`](./flox-init.md) [`flox-push(1)`](./flox-push.md), -[`flox-pull(1)`](./flox-pull.md) diff --git a/docs/reference/command-reference/flox-edit.md b/docs/reference/command-reference/flox-edit.md deleted file mode 100644 index 35e05df6..00000000 --- a/docs/reference/command-reference/flox-edit.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: flox edit -description: Command reference for the `flox edit` command. ---- - -# `flox edit` command - -## NAME - -flox-edit - edit the declarative environment configuration - -## SYNOPSIS - - flox [] edit - [-d= | -r=] - [[-f=] | -n= | --sync | --reset] - -## DESCRIPTION - -### Transactionally edit the environment manifest. - -By default invokes an editor with a copy of the local manifest for the -user to interactively edit. The editor is found by querying `$EDITOR`, -`$VISUAL`, and then by looking for common editors in `$PATH`. The -manifest of an environment on FloxHub or in a different directory can be -edited via the `-r` or `-d` flags respectively. See -[`manifest.toml(5)`](./manifest.toml.md) for more details on the -manifest format. - -Once the editor is closed the environment is built in order to validate -the edit. If the build fails you are given a change to continue editing -the manifest, and if you decline, the edit is discarded. This -transactional editing prevents an edit from leaving the environment in a -broken state. One exception is the `-n` flag, which renames a local -environment but does not rebuild it. - -The environment can be edited non-interactively via the `-f` flag, which -replaces the contents of the manifest with those of the provided file. - -### Sync the local manifest with the current generation. - -When using environments that were pushed to or pulled from FloxHub, -changes to the local manifest in `.flox/env/manifest.toml` will block -the use of the environment commands -`flox {install, uninstall, edit, upgrade}`. In this case, a new -generation has to be created from the local manifest first or the -changes discarded. Run `flox edit --reset` to discard local changes and -reset to the current latest generation, or `flox edit --sync` to create -a new generation. - -## OPTIONS - -### Edit Options - -`-f`, `--file` -Replace environment manifest with that in ``. If `` is `-`, -reads from stdin. - -`-n`, `--name` -Rename the environment to ``. Only works for local environments. - -`-s`, `--sync` -Create a new generation from the current local environment (Only -available for managed environments) - -`-r`, `--reset` -Reset the environment to the current generation (Only available for -managed environments) - -### Environment Options - -If no environment is specified for an environment command, the -environment in the current directory or the active environment that was -last activated is used. - -`-d`, `--dir` -Path containing a .flox/ directory. - -`-r`, `--remote` -A remote environment on FloxHub, specified in the form `/`. - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## ENVIRONMENT VARIABLES - -`$EDITOR`, `$VISUAL` -Override the default editor used for editing environment manifests and -commit messages. - -## SEE ALSO - -[`flox-push(1)`](./flox-push.md), [`flox-pull(1)`](./flox-pull.md), -[`flox-activate(1)`](./flox-activate.md) diff --git a/docs/reference/command-reference/flox-envs.md b/docs/reference/command-reference/flox-envs.md deleted file mode 100644 index c56a704d..00000000 --- a/docs/reference/command-reference/flox-envs.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: flox envs -description: Command reference for the `flox envs` command. ---- - -# `flox envs` command - -## NAME - -flox-envs - show active and available environments - -## SYNOPSIS - - flox [] envs - [--active] - [--json] - -## DESCRIPTION - -This command can be used to list available environments on the local -machine. When one or more environments are active, the last activated -environment will be listed first and printed in **bold**. - -Whenever an environment is used with any `flox` command it is registered -to a user specific global registry. `flox envs` will list all -environments known to it through the registry. Environments that are -present on the local system may not show up until they are used the -first time. Similarly, if an environment is changed (e.g. deleted and -replaced by an environment with different metadata), the change may not -show until the new environment is used. - -## OPTIONS - -### Edit Options - -`--active` -Show only active environments - -`--json` -Format the output as JSON - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## SEE ALSO - -[`flox-init(1)`](./flox-init.md), [`flox-pull(1)`](./flox-pull.md), -[`flox-activate(1)`](./flox-activate.md) diff --git a/docs/reference/command-reference/flox-init.md b/docs/reference/command-reference/flox-init.md deleted file mode 100644 index 78fe9c38..00000000 --- a/docs/reference/command-reference/flox-init.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: flox init -description: Command reference for the `flox init` command. ---- - -# `flox init` command - -## NAME - -flox-init - initialize a Flox environment - -## SYNOPSIS - - flox [] init - [-n ] - [-d ] - [--auto-setup] - -## DESCRIPTION - -Create a new empty environment in the current directory. - -The name of the environment will be the basename of the current -directory or `default` if the current directory is `$HOME`. The `--name` -flag can be used to give the environment a specific name. - -By default the environment will be created in the current directory. -Flox will add a directory `$PWD/.flox` containing all relevant -environment metadata. The `--dir` flag can be used to create an -environment in another location. - -If an environment already exists in the current directory, or the path -specified using `--dir` exists, an error is returned. - -`init` will try to detect languages being used in the containing -directory, and it will prompt with suggestions for packages or -activation scripts to be added to the environment. These suggestions can -be taken without prompting by passing `--auto-setup`. The suggestions -can be accepted but then edited using `flox edit`. Currently, -suggestions are made for Python and Nodejs. - -## OPTIONS - -### Init Options - -`-n `, `--name ` -What to name the new environment (default: current directory). - -`-d `, `--dir ` -Directory to create the environment in (default: current directory). - -`--auto-setup` -Apply Flox recommendations for the environment based on what languages -are being used in the containing directory. - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## SEE ALSO - -[`flox-activate(1)`](./flox-activate.md), -[`flox-install(1)`](./flox-install.md), diff --git a/docs/reference/command-reference/flox-install.md b/docs/reference/command-reference/flox-install.md deleted file mode 100644 index fb345ec6..00000000 --- a/docs/reference/command-reference/flox-install.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: flox install -description: Command reference for the `flox install` command. ---- - -# `flox install` command - -## NAME - -flox-install - install packages to an environment - -## SYNOPSIS - - flox [] install - [-i ] - [[-i ] ] ... - -## DESCRIPTION - -Install packages to an environment. - -Package installation is transactional. During an installation attempt -the environment is built in order to validate that the environment isn’t -broken (for example, in rare cases packages may provide files that -conflict). If building the environment fails, including any of the -consitituent packages, the attempt is discarded and the environment is -unmodified. If the build succeeds, the environment is atomically -updated. - -If a requested package is already installed, nothing is done. If -multiple packages are requested and some of them are already installed, -only the new packages are installed and the transaction will still -succeed as long as the build succeeds. - -You may also specify packages to be installed via -[`flox-edit(1)`](./flox-edit.md), which allows specifying a variety of -options for package installation. See -[`manfifest-toml(1)`](./manifest.toml.md) for more details on the -available options. - -### Install ID - -The name of a package as it exists in the manifest is referred to as the -“install ID”. This ID is separate from the pkg-path and provides a -shorthand for packages with long names such as `python310Packages.pip`. -Install IDs also provide a way to give packages more semantically -meaningful, convenient, or aesthetically pleasing names in the manifest -(e.g. `node21` instead of `nodejs_21`). When not explicitly provided, -the install ID is inferred based on the pkg-path. For pkg-paths that -consist of a single attribute (e.g. `ripgrep`) the install ID is set to -that attribute. For pkg-paths that consist of multiple attributes -(e.g. `python310Packages.pip`) the install ID is set to the last -attribute in the pkg-path (e.g. `pip`). - -As an advanced feature, a Nix flake installable may be specified instead -of a pkg-path, and in this case the install ID is inferred from the -attribute path specified, or if no attribute path is provided, the -install ID is inferred from the flake reference. - -### Package names - -Packages are organized in a hierarchical structure such that certain -packages are found at the top level (e.g. `ripgrep`), and other packages -are found under package sets (e.g. `python310Packages.pip`). We call -this location within the catalog the “pkg-path”. - -The pkg-path is searched when you execute a `flox search` command. The -pkg-path is what’s shown by `flox show`. Finally, the pkg-path appears -in your manifest after a `flox install`. - -``` toml -[install] -ripgrep.pkg-path = "ripgrep" -pip.pkg-path = "python310Packages.pip" -``` - -## OPTIONS - -### Install Options - -`-i`, `--id` -The install ID of the package as it will appear in the manifest - -`` -The pkg-path of the package to install as shown by ‘flox search’ Append -`@` to specify a version requirement. - -Alternatively, an arbitrary Nix flake installable may be specified. See -[`manfifest-toml(1)`](./manifest.toml.md) for more details. - -### Environment Options - -If no environment is specified for an environment command, the -environment in the current directory or the active environment that was -last activated is used. - -`-d`, `--dir` -Path containing a .flox/ directory. - -`-r`, `--remote` -A remote environment on FloxHub, specified in the form `/`. - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -### SEE ALSO - -[`flox-uninstall(1)`](./flox-uninstall.md), -[`flox-edit(1)`](./flox-edit.md), -[`manifest.toml(5)`](./manifest.toml.md) diff --git a/docs/reference/command-reference/flox-list.md b/docs/reference/command-reference/flox-list.md deleted file mode 100644 index 99230e0e..00000000 --- a/docs/reference/command-reference/flox-list.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: flox list -description: Command reference for the `flox list` command. ---- - -# `flox list` command - -## NAME - -flox-list - list packages installed in an environment - -## SYNOPSIS - - flox [] list - [-d= | -r=] - [-e | -c | -n | -a] - -## DESCRIPTION - -List packages installed in an environment. The options `-n`, `-e`, and -`-a` exist to provide varying levels of detail in the output. - -## OPTIONS - -### List Options - -`-e`, `--extended` -Show the install ID, pkg-path, and version of each package (default). - -`-c`, `--config` -Show the raw contents of the manifest. - -`-n`, `--name` -Show only the install ID of each package. - -`-a`, `--all` -Show all available package information including priority and license. - -### Environment Options - -If no environment is specified for an environment command, the -environment in the current directory or the active environment that was -last activated is used. - -`-d`, `--dir` -Path containing a .flox/ directory. - -`-r`, `--remote` -A remote environment on FloxHub, specified in the form `/`. - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## SEE ALSO - -[`flox-install(1)`](./flox-install.md) diff --git a/docs/reference/command-reference/flox-pull.md b/docs/reference/command-reference/flox-pull.md deleted file mode 100644 index 33320b27..00000000 --- a/docs/reference/command-reference/flox-pull.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: flox pull -description: Command reference for the `flox pull` command. ---- - -# `flox pull` command - -## NAME - -flox-pull - pull environment from FloxHub - -## SYNOPSIS - - flox [] pull - [-d=] - [-a] - [-r=/ | / | [-f]] - -## DESCRIPTION - -Pull an environment from FloxHub and create a local reference to it, or, -if an environment has already been pulled, retrieve any updates. - -When pulling an environment for the first time, `-d` specifies the -directory in which to create that environment. The remote environment is -specified in the form `/`. It may optionally be preceded by -`-r`, but `-r` is not necessary and is accepted simply for consistency -with other environment commands. - -When pulling an environment that has already been pulled, `-d` specifies -which environment to sync. If `-d` is not specified and the current -directory contains an environment, that environment is synced. `-f` may -only be specified in this case, forceably updating the environment -locally even if there are local changes not reflected in the remote -environment. `/` may be specified in this case and will -replace the environment with the specified environment. - -A remote environment may not support the architecture or operating -system of the local system pulling the environment, in which case `-a` -may be passed to forceably add the current system to the environment’s -manifest. This may create a broken environment that cannot be pushed -back to FloxHub until it is repaired with -[`flox-edit(1)`](./flox-edit.md). See -[`manifest.toml(5)`](./manifest.toml.md) for more on multi-system -environments. - -## OPTIONS - -### Pull Options - -`-d`, `--dir` -Directory to pull an environment into, or directory that contains an -environment that has already been pulled (default: current directory). - -`-a`, `--add-system` -Forceably add current system to the environment, even if incompatible. - -`-r /`, `--remote /` -ID of the environment to pull. - -`/` -ID of the environment to pull. - -`-f`, `--force` -Forceably overwrite the local copy of the environment. - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## SEE ALSO - -[`flox-push(1)`](./flox-push.md) [`flox-edit(1)`](./flox-edit.md) -[`manifest.toml(5)`](./manifest.toml.md) diff --git a/docs/reference/command-reference/flox-push.md b/docs/reference/command-reference/flox-push.md deleted file mode 100644 index b8e36b06..00000000 --- a/docs/reference/command-reference/flox-push.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: flox push -description: Command reference for the `flox push` command. ---- - -# `flox push` command - -## NAME - -flox-push - send environment to FloxHub - -## SYNOPSIS - - flox [] push - [-d=] - [-o=] - [-f] - -## DESCRIPTION - -Move an environment’s manifest to FloxHub or sync local changes to an -environment to FloxHub. - -After pushing, the remote environment can be referred to as -`/`. - -A path environment contains a manifest file and lock file which are -stored locally and possibly committed to version control. Pushing the -environment moves the manifest and lock file to FloxHub, leaving a -reference to the revision of the environment stored locally. - -Once the environment has been pushed, it can be used directly with the -`--remote` option, or it can be used and edited locally before syncing -with `flox push`. See [`flox-edit(1)`](./flox-edit.md), -[`flox-install(1)`](./flox-install.md), and -[`flox-uninstall(1)`](./flox-uninstall.md) for editing the environment. - -In the same way as a git repo, local changes to an environment that has -been pushed may diverge from the environment on FloxHub if `flox push` -is run from a different host. Passing `--force` to `flox push` will -cause it to overwrite any changes on FloxHub with local changes to the -environment. - -## OPTIONS - -### Push Options - -`-d`, `--dir` -Directory to push the environment from (default: current directory). - -`-o`, `--owner` -FloxHub owner to push environment to (default: current FloxHub user). - -`-f`, `--force` -Forceably overwrite the remote copy of the environment. - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## SEE ALSO - -[`flox-pull(1)`](./flox-pull.md) diff --git a/docs/reference/command-reference/flox-search.md b/docs/reference/command-reference/flox-search.md deleted file mode 100644 index 9cd5468b..00000000 --- a/docs/reference/command-reference/flox-search.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: flox search -description: Command reference for the `flox search` command. ---- - -# `flox search` command - -## NAME - -flox-search - search for packages - -## SYNOPSIS - - flox [] search - [--json] - [-a] - - -## DESCRIPTION - -Search for available packages. - -A limited number of search results are reported by default for brevity. -The full result set can be returned via the `-a` flag. - -Only the package name and description are shown by default. Structured -search results can be returned via the `--json` flag. More specific -information for a single package is available via the -[`flox-show(1)`](./flox-show.md) command. - -### Package names - -Packages are organized in a hierarchical structure such that certain -packages are found at the top level (e.g. `ripgrep`), and other packages -are found under package sets (e.g. `python310Packages.pip`). We call -this location within the catalog the “pkg-path”. - -The pkg-path is searched when you execute a `flox search` command. The -pkg-path is what’s shown by `flox show`. Finally, the pkg-path appears -in your manifest after a `flox install`. - -``` toml -[install] -ripgrep.pkg-path = "ripgrep" -pip.pkg-path = "python310Packages.pip" -``` - -### Fuzzy search - -`flox search` uses a fuzzy search mechanism that tries to match either -some portion of the pkg-path or description. - -## OPTIONS - -### Search Options - -`` -The package name to search for. - -`--json` -Display the search results in JSON format. - -`-a`, `--all` -Display all search results (default: at most 10). - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## SEE ALSO - -[`flox-show(1)`](./flox-show.md) diff --git a/docs/reference/command-reference/flox-services-logs.md b/docs/reference/command-reference/flox-services-logs.md deleted file mode 100644 index e153762e..00000000 --- a/docs/reference/command-reference/flox-services-logs.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: flox services logs -description: Command reference for the `flox services logs` command. ---- - -# `flox services logs` command - -## NAME - -flox-services-logs - show logs of services - -## SYNOPSIS - - flox [] services logs - [-d= | -r=] - [--follow] - [-n=] - [] ... - -## DESCRIPTION - -Display the logs of the specified services. - -If no services are specified, then the `--follow` flag is required and -logs from all services will be printed in real time. - -One or more service names specified with the `--follow` flag will follow -the logs for the specified services. - -If a service name is supplied without the `--follow` flag then all of -the available logs are displayed for that service. If specified with the -`-n` flag then only the most recent `` lines from that service are -displayed. - -An error will be returned if a specified service does not exist. - -## OPTIONS - -`-d`, `--dir` -Path containing a .flox/ directory. - -`--follow` -Follow log output for the specified services. Required when no service -names are supplied. - -`-n`, `--tail` -Display only the last `` lines from the logs of the specified -services. - -`` -Which service(s) to display logs for. When omitted logs from all -services will be displayed but the `--follow` flag is required. - -### Environment Options - -If no environment is specified for an environment command, the -environment in the current directory or the active environment that was -last activated is used. - -`-d`, `--dir` -Path containing a .flox/ directory. - -`-r`, `--remote` -A remote environment on FloxHub, specified in the form `/`. - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## EXAMPLES: - -Follow logs for all services: - - $ flox services logs --follow - service1: hello - service2: hello - ... - -Follow logs for a subset of services: - - $ flox services logs --follow service1 service3 - service1: hello - service3: hello - ... - -Display all available logs for a single service: - - $ flox services logs myservice - starting... - running... - stopping... - completed - -## SEE ALSO - -[`flox-activate(1)`](./flox-activate.md) -[`flox-services-start(1)`](./flox-services-start.md) diff --git a/docs/reference/command-reference/flox-services-restart.md b/docs/reference/command-reference/flox-services-restart.md deleted file mode 100644 index 524b046e..00000000 --- a/docs/reference/command-reference/flox-services-restart.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: flox services restart -description: Command reference for the `flox services restart` command. ---- - -# `flox services restart` command - -## NAME - -flox-services-restart - restart running services - -## SYNOPSIS - - flox [] services restart - [-d= | -r=] - [] ... - -## DESCRIPTION - -Restarts the specified services. - -If no services are specified, stops all running services and starts new -services using the latest build of the environment. If one or more -services are running, then the specified services are started using the -service config that the running services were started with. - -If one or more services are running, the specified services will be -started using the service config that the running services were started -with. - -When all services are restarted, they are started from an ephemeral -activation that uses the latest build of the environment. This may not -be the build of the environment that your shell has activated, so the -environment variables present for services may be different from the -ones in your shell. To ensure that your shell and the services have the -same environment, reactivate your environment after making edits to the -manifest. - -An error is displayed if the specified service does not exist. - -## OPTIONS - -`-d`, `--dir` -Path containing a .flox/ directory. - -`` -The name(s) of the services to restart. - -### Environment Options - -If no environment is specified for an environment command, the -environment in the current directory or the active environment that was -last activated is used. - -`-d`, `--dir` -Path containing a .flox/ directory. - -`-r`, `--remote` -A remote environment on FloxHub, specified in the form `/`. - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## EXAMPLES: - -Restart a single service: - - $ flox services restart myservice - ✅ Service 'myservice' restarted. - -Restart all services: - - $ flox services restart - ✅ Service 'service1' restarted. - ✅ Service 'service2' restarted. - ✅ Service 'service3' restarted. - -## SEE ALSO - -[`flox-activate(1)`](./flox-activate.md) diff --git a/docs/reference/command-reference/flox-services-start.md b/docs/reference/command-reference/flox-services-start.md deleted file mode 100644 index c91fcfa4..00000000 --- a/docs/reference/command-reference/flox-services-start.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: flox services start -description: Command reference for the `flox services start` command. ---- - -# `flox services start` command - -## NAME - -flox-services-start - start services - -## SYNOPSIS - - flox [] services start - [-d= | -r=] - [] ... - -## DESCRIPTION - -Starts the specified services. - -If any services are currently running, a warning will be displayed for -each specified service that is already running but the command will -still succeed. If a specified service does not exist, an error will -displayed and no services will be started. - -If no services are currently running, then the services will be started -from an ephemeral activation in order to use the most recent build of -the environment. This may be different from the build of the environment -that the current shell has activated, so the services and your shell may -have different environment variables or values. To ensure that your -shell and the services have the same environment, reactivate your -environment after making edits to the manifest. - -A remote environment can only have a single set of running services, -regardless of how many times the environment is activated concurrently. - -## OPTIONS - -`-d`, `--dir` -Path containing a .flox/ directory. - -`` -The name(s) of the services to start. - -### Environment Options - -If no environment is specified for an environment command, the -environment in the current directory or the active environment that was -last activated is used. - -`-d`, `--dir` -Path containing a .flox/ directory. - -`-r`, `--remote` -A remote environment on FloxHub, specified in the form `/`. - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## EXAMPLES: - -Start a service named ‘server’: - - $ flox services start server - -Start all services: - - $ flox services start - -Attempt to start a service that doesn’t exist: - - $ flox services start myservice doesnt_exist - ❌ ERROR: Service 'doesnt_exist' not found. - -Attempt to start a service that is already running: - - $ flox services start running not_running - ✅ Service 'not_running' started - ⚠️ Service 'running' is already running - -## SEE ALSO - -[`flox-activate(1)`](./flox-activate.md) -[`flox-services-stop(1)`](./flox-services-stop.md) diff --git a/docs/reference/command-reference/flox-services-status.md b/docs/reference/command-reference/flox-services-status.md deleted file mode 100644 index f90078f5..00000000 --- a/docs/reference/command-reference/flox-services-status.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: flox services status -description: Command reference for the `flox services status` command. ---- - -# `flox services status` command - -## NAME - -flox-services-status - display the status of services - -## SYNOPSIS - - flox [] services status - [-d= | -r=] - [--json] - [] ... - -## DESCRIPTION - -Displays the status of one or more services. - -If no services are specified, then all services will be displayed. If no -services have been started for this environment, an error will be -displayed. An error will also be displayed if one of the specified -services does not exist. - -## OPTIONS - -`-d`, `--dir` -Path containing a .flox/ directory. - -`--json` -Print statuses formatted as JSON. Each service is printed as a single -JSON object on its own line. - -### Environment Options - -If no environment is specified for an environment command, the -environment in the current directory or the active environment that was -last activated is used. - -`-d`, `--dir` -Path containing a .flox/ directory. - -`-r`, `--remote` -A remote environment on FloxHub, specified in the form `/`. - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## EXAMPLES: - -Display statuses for all services: - - $ flox services status - NAME STATUS PID - sleeping Running 89718 - myservice Running 12345 - -Display the status of a single service: - - $ flox services status myservice - NAME STATUS PID - myservice Running 12345 - -## SEE ALSO - -[`flox-activate(1)`](./flox-activate.md) -[`flox-services-start(1)`](./flox-services-start.md) diff --git a/docs/reference/command-reference/flox-services-stop.md b/docs/reference/command-reference/flox-services-stop.md deleted file mode 100644 index 26a77ccb..00000000 --- a/docs/reference/command-reference/flox-services-stop.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: flox services stop -description: Command reference for the `flox services stop` command. ---- - -# `flox services stop` command - -## NAME - -flox-services-stop - stop running services - -## SYNOPSIS - - flox [] services stop - [-d= | -r=] - [] ... - -## DESCRIPTION - -Stops the specified running services. - -If no services are specified, then all services will be stopped. If any -of the specified services are not currently running, a warning will be -displayed and the remaining services will be stopped. - -If any of the specified services do not exist, an error will be returned -and no services will be stopped. If an error is encountered while -stopping one of the specified services, the remaining services will -still be stopped a warning will be displayed for the services that -failed to stop, and a non-zero exit code will be returned. - -## OPTIONS - -`-d`, `--dir` -Path containing a .flox/ directory. - -`` -The name(s) of the services to stop. - -### Environment Options - -If no environment is specified for an environment command, the -environment in the current directory or the active environment that was -last activated is used. - -`-d`, `--dir` -Path containing a .flox/ directory. - -`-r`, `--remote` -A remote environment on FloxHub, specified in the form `/`. - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## EXAMPLES: - -Stop a running service named ‘server’: - - $ flox services stop server - -Stop all running services: - - $ flox services stop - -Attempt to stop a service that doesn’t exist: - - $ flox services stop myservice doesnt_exist - ❌ ERROR: Service 'doesnt_exist' not found. - -Attempt to stop a service that isn’t running: - - $ flox services stop running not_running - ⚠️ Service 'not_running' is not running - ✅ Service 'running' stopped - -## SEE ALSO - -[`flox-activate(1)`](./flox-activate.md) diff --git a/docs/reference/command-reference/flox-show.md b/docs/reference/command-reference/flox-show.md deleted file mode 100644 index e057a6cf..00000000 --- a/docs/reference/command-reference/flox-show.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: flox show -description: Command reference for the `flox show` command. ---- - -# `flox show` command - -## NAME - -flox-show - show detailed information about a single package - -## SYNOPSIS - - flox [] show - -## DESCRIPTION - -Show detailed information about a single package. - -The default output includes the package description, name, and version. - -### Package names - -Packages are organized in a hierarchical structure such that certain -packages are found at the top level (e.g. `ripgrep`), and other packages -are found under package sets (e.g. `python310Packages.pip`). We call -this location within the catalog the “pkg-path”. - -The pkg-path is searched when you execute a `flox search` command. The -pkg-path is what’s shown by `flox show`. Finally, the pkg-path appears -in your manifest after a `flox install`. - -``` toml -[install] -ripgrep.pkg-path = "ripgrep" -pip.pkg-path = "python310Packages.pip" -``` - -## OPTIONS - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -### Show Options - -`` -Package name to show details for. - -## EXAMPLES: - -Display detailed information about the `ripgrep` package: - - $ flox show ripgrep - ripgrep - A utility that combines the usability of The Silver Searcher with the raw speed of grep - ripgrep@13.0.0 - ripgrep@14.1.0 - -## SEE ALSO - -[`flox-search(1)`](./flox-search.md), -[`flox-install(1)`](./flox-install.md) diff --git a/docs/reference/command-reference/flox-uninstall.md b/docs/reference/command-reference/flox-uninstall.md deleted file mode 100644 index 6555b0a7..00000000 --- a/docs/reference/command-reference/flox-uninstall.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: flox uninstall -description: Command reference for the `flox uninstall` command. ---- - -# `flox uninstall` command - -## NAME - -flox-uninstall - remove packages from an environment - -## SYNOPSIS - - flox [] (uninstall|rm) - [-d= | -r=] - - -## DESCRIPTION - -Uninstall packages from an environment. - -Just like package installation, package uninstallation is transactional. -See [`flox-install(1)`](./flox-install.md) for more details on -transactions. Requesting to uninstall multiple packages where at least -one of them was not previously installed will cause the transaction to -fail and no packages will be uninstalled. - -## OPTIONS - -### Remove Options - -`` -The install IDs or package paths of the packages to remove. If the -manifest contains both an install ID and a package with matching package -path, the install ID takes precedence. If the same package path is -installed under different install IDs, an error is returned. A package -path can optionally contain the original version constraint. - -### Environment Options - -If no environment is specified for an environment command, the -environment in the current directory or the active environment that was -last activated is used. - -`-d`, `--dir` -Path containing a .flox/ directory. - -`-r`, `--remote` -A remote environment on FloxHub, specified in the form `/`. - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## SEE ALSO - -[`flox-install(1)`](./flox-install.md) diff --git a/docs/reference/command-reference/flox-update.md b/docs/reference/command-reference/flox-update.md deleted file mode 100644 index e5e813d7..00000000 --- a/docs/reference/command-reference/flox-update.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: flox update -description: Command reference for the `flox update` command. ---- - -# `flox update` command - -> **Warning:** This command is **deprecated** and no longer supported - -## NAME - -flox-update - update the global base catalog or an environment’s base -catalog - -## SYNOPSIS - - flox [] update - [--global | (-d= | -r=/)] - -## DESCRIPTION - -Update an environment’s base catalog, or update the global base catalog -if `--global` is specified. - -The base catalog is a collection of packages used by various flox -subcommands. - -The global base catalog provides packages for -[`flox-search(1)`](./flox-search.md) and -[`flox-show(1)`](./flox-show.md) when not using an environment, and it -is used to initialize an environment’s base catalog. - -An environment’s base catalog provides packages for -[`flox-search(1)`](./flox-search.md) and -[`flox-show(1)`](./flox-show.md) when using that environment, and it -provides packages for [`flox-install(1)`](./flox-install.md) and -[`flox-upgrade(1)`](./flox-upgrade.md). - -Note that updating an environment’s base catalog and upgrading packages -are two separate options. Upgrading packages will usually require -running an update command followed by a -[`flox-upgrade`](./flox-upgrade.md). - -## OPTIONS - -### Update Options - -`--global` -Update the global base catalog - -### Environment Options - -If no environment is specified for an environment command, the -environment in the current directory or the active environment that was -last activated is used. - -`-d`, `--dir` -Path containing a .flox/ directory. - -`-r`, `--remote` -A remote environment on FloxHub, specified in the form `/`. - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## SEE ALSO - -[`flox-upgrade(1)`](./flox-upgrade.md) diff --git a/docs/reference/command-reference/flox-upgrade.md b/docs/reference/command-reference/flox-upgrade.md deleted file mode 100644 index 5251cf21..00000000 --- a/docs/reference/command-reference/flox-upgrade.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: flox upgrade -description: Command reference for the `flox upgrade` command. ---- - -# `flox upgrade` command - -## NAME - -flox-upgrade - upgrade packages in an environment - -## SYNOPSIS - - flox [] upgrade - [-d= | -r=/] - []... - -## DESCRIPTION - -Upgrade packages in an environment to versions present in the catalog. - -When no arguments are specified, all packages in the environment are -upgraded. - -Packages to upgrade can be specified by either pkg-group name, or by ID. -If the specified argument is both a pkg-group name and an install ID, -both the package with the install ID and packages belonging to the -pkg-group are upgraded. - -Packages without a specified pkg-group in the manifest are placed in a -pkg-group named ‘toplevel’. The packages in that pkg-group can be -upgraded without updating any other pkg-groups by passing ‘toplevel’ as -the pkg-group name. - -See [`manifest.toml(5)`](./manifest.toml.md) for more on using -pkg-groups. - -## OPTIONS - -### Upgrade Options - -`` -Install ID or pkg-group to upgrade. - -### Environment Options - -If no environment is specified for an environment command, the -environment in the current directory or the active environment that was -last activated is used. - -`-d`, `--dir` -Path containing a .flox/ directory. - -`-r`, `--remote` -A remote environment on FloxHub, specified in the form `/`. - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## SEE ALSO - -[`manifest.toml(5)`](./manifest.toml.md) diff --git a/docs/reference/command-reference/flox.md b/docs/reference/command-reference/flox.md deleted file mode 100644 index 991348e1..00000000 --- a/docs/reference/command-reference/flox.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: flox -description: Command reference for the `flox` command. ---- - -# `flox` command - -## NAME - -flox - developer environments you can take with you - -## SYNOPSIS - - flox [] - [] - [] ... - -## DESCRIPTION - -Flox is a virtual environment and package manager all in one. - -With flox you create environments that layer and provide dependencies -just where it matters, making them portable across the full software -lifecycle. - -### Command Line Completions - -Flox ships with command line completions for `bash`, `fish` and `zsh`. -These completions are installed alongside Flox. - -## OPTIONS - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -### flox Options - -`--version` -Print `flox` version. - -## COMMANDS - -Flox commands are grouped into categories pertaining to local -development, sharing environments, and administration. - -### Local Development Commands - -`init` -Create an environment in the current directory. - -`activate` -Enter the environment, type `exit` to leave. - -`search` -Search for system or library packages to install. - -`show` -Show details about a single package. - -`install`, `i` -Install packages into an environment. - -`uninstall` -Uninstall installed packages from an environment. - -`edit` -Edit the declarative environment configuration file. - -`list`, ‘l’ -List packages installed in an environment. - -`delete` -Delete an environment. - -### Sharing Commands - -`push` -Send an environment to FloxHub. - -`pull` -Pull an environment from FloxHub. - -### Additional Commands - -`update` -Update an environment’s base catalog or update the global base catalog. - -`upgrade` -Upgrade packages in an environment. - -`config` -View and set configuration options. - -`auth` -FloxHub authentication commands. - -## ENVIRONMENT VARIABLES - -`$FLOX_DISABLE_METRICS` -Variable for disabling the collection/sending of metrics data. If set to -`true`, prevents Flox from submitting basic metrics information such as -a unique token and the subcommand issued. - -`$EDITOR`, `$VISUAL` -Override the default editor used for editing environment manifests and -commit messages. - -`$SSL_CERT_FILE`, `$NIX_SSL_CERT_FILE` -If set, overrides the path to the default flox-provided SSL certificate -bundle. Set `NIX_SSL_CERT_FILE` to only override packages built with -Nix, and otherwise set `SSL_CERT_FILE` to override the value for all -packages. - -See also: [Nix environment variables - -`NIX_SSL_CERT_FILE`](https://nixos.org/manual/nix/stable/installation/env-variables.html#nix_ssl_cert_file) - -## SEE ALSO - -[`flox-init`(1)](./flox-init.md), -[`flox-activate`(1)](./flox-activate.md), -[`flox-install`(1)](./flox-install.md), -[`flox-uninstall(1)`](./flox-uninstall.md), -[`flox-upgrade`(1)](./flox-upgrade.md), -[`flox-search`(1)](./flox-search.md), [`flox-show(1)`](./flox-show.md), -[`flox-edit`(1)](./flox-edit.md), -[`manifest-toml`(5)](./manifest.toml.md), -[`flox-list`(1)](./flox-list.md), [`flox-auth(1)`](./flox-auth.md), -[`flox-push`(1)](./flox-push.md), [`flox-pull`(1)](./flox-pull.md), -[`flox-delete`(1)](./flox-delete.md), -[`flox-config`(1)](./flox-config.md) diff --git a/docs/reference/command-reference/manifest.toml.md b/docs/reference/command-reference/manifest.toml.md deleted file mode 100644 index 5b56f316..00000000 --- a/docs/reference/command-reference/manifest.toml.md +++ /dev/null @@ -1,475 +0,0 @@ ---- -title: manifest.toml -description: Reference for the manifest.toml format. ---- - -# `manifest.toml` - -## NAME - -manifest.toml - declarative environment configuration format - -## SYNOPSIS - -The `manifest.toml` file is a declarative format for specifying the -packages installed in an environment, environment variables to make -available to the environment, a shell script to run upon activation of -the environment, and other options to change the behavior of the -environment. - -## DESCRIPTION - -Flox environments come with a declarative manifest in [TOML -format](https://toml.io/en/v1.0.0). An environment can be defined -entirely by this one file. The file is divided into just a few sections -that are represented as TOML tables: - -- [`[install]`](#install) -- [`[vars]`](#vars) -- [`[hook]`](#hook) -- [`[profile]`](#profile) -- [`[services]`](#services) -- [`[options]`](#options) - -### `[install]` - -The `[install]` table is the core of the environment, specifying which -packages you’d like installed in the environment. An example of the -`[install]` table is shown below: - -``` toml -[install] -ripgrep.pkg-path = "ripgrep" -pip.pkg-path = "python310Packages.pip" -``` - -Since this is TOML, equivalent ways of writing this would be - -``` toml -[install] -ripgrep = { pkg-path = "ripgrep" } -pip = { pkg-path = "python310Packages.pip" } -``` - -or - - [install.ripgrep] - pkg-path = "ripgrep" - - [install.pip] - pkg-path = "python310Packages.pip" - -Flox will use the first format by default when automatically editing the -manifest. - -#### Package names - - - -Packages are organized in a hierarchical structure such that certain -packages are found at the top level (e.g. `ripgrep`), and other packages -are found under package sets (e.g. `python310Packages.pip`). We call -this location within the catalog the “pkg-path”. - -The pkg-path is searched when you execute a `flox search` command. The -pkg-path is what’s shown by `flox show`. Finally, the pkg-path appears -in your manifest after a `flox install`. - -``` toml -[install] -ripgrep.pkg-path = "ripgrep" -pip.pkg-path = "python310Packages.pip" -``` - -#### Package descriptors - -Each entry in the `[install]` table is a key-value pair. The key in the -key-value pair (e.g. `ripgrep`, `pip`) is referred to as an “install -ID”, and represents the name by which you will refer to a particular -package e.g. if you wanted to uninstall or upgrade the package. Install -IDs are inferred from the last attribute in the pkg-path, but may also -be specified either at install-time via the `-i` option or interactively -via [`flox-edit(1)`](./flox-edit.md). - -The value in the key-value pair is called a “package descriptor”. A -package is specified by a number of available options which are separate -from the install ID, so you are free to change them independently of one -another. This allows you to change package details while keeping a -stable install ID, for example upgrading from `gcc.pkg-path = "gcc12"` -to `gcc.pkg-path = "gcc13"`. - -Most package descriptors will be catalog descriptors, which allow -specifying packages from the Flox catalog. A second format, flake -descriptors, is also supported, which allows specifying software to -install from an arbitrary Nix flake. - -##### Catalog descriptors - -The full list of catalog descriptor options is: - - Descriptor ::= { - pkg-group = null | - , version = null | - , systems = null | [, ...] - , pkg-path = - , priority = null | - } - -Only `pkg-path` is required. - -By specifying some of these options you create a set of requirements -that the installed program must satisfy, otherwise installation will -fail. - -By default, all packages belong to the same `pkg-group`, which means -providing specific versions for two different packages can quickly lead -to installation failures. To avoid such failures, either give a looser -`version` constraint, or move one of the packages to a different package -group. - -Each option is described below: - -`pkg-group` -Marks a package as belonging to a pkg-group. - -The pkg-group is a collection of software that is known to work together -at a point in time. Adding packages to a pkg-group enables packages in -the pkg-group to share the same libraries and dependencies, which -ensures maximum compatibility and minimizes the size of the environment. - -Packages are marked as belonging to a pkg-group simply by setting this -option to the name of the pkg-group. Packages that do not have a -pkg-group specified belong to the same group. - -Multiple pkg-groups may resolve to the same version of the catalog. -Pkg-groups are upgraded as a unit, ensuring that the packages within the -pkg-group continue to work together. See -[`flox-upgrade(1)`](./flox-upgrade.md) for more details on how -pkg-groups and packages interact during upgrades. - -`version` -Requires that the package match either an exact version or a semver -range. - -The semantic version can be specified with the typical qualifiers such -as `^`, `>=`, etc. Semantic versions that do not specify all three -fields (`MAJOR.MINOR.PATCH`) will treat the unspecified fields as -wildcards. This instructs Flox to find the latest versions for those -fields. For example `version = "1.2"` would select the latest version in -the `1.2.X` series. - -`systems` -A list of systems on which to install this package. When omitted this -defaults to the same systems that the manifest specifies that it -supports via `options.systems`. - -`pkg-path` -The abbreviated location of a package within a catalog. A pkg-path is a -sequence of one or more attributes joined by a delimiter. For example, -both `ripgrep` and `python310Packages.pip` are pkg-paths. A pkg-path -that contains more than one attribute can be represented as either a -single string that contains a ‘.’-delimited sequence of the attributes, -or it can be represented as a TOML array of strings where each string is -an attribute. For example, both `"python310Packages.pip"` and -`["python310Packages", "pip"]` are equivalent for the `pkg-path` option. - -This option is mutually exclusive with `abs-path`. - -`priority` -A priority used to resolve file conflicts where lower values indicate -higher priority. - -Each package internally has `/bin`, `/man`, `/include`, and other -directories for the files they provide. These directories from all -packages in the environment are merged when building the environment. -Two packages that provide the same `/bin/foo` file cause a conflict, and -it’s ambiguous which file should ultimately be placed into the -environment. Such conflicts can be resolved by assigning different -priorities to the conflicting packages. - -The default priority is 5. Packages with a lower `priority` value will -take precedence over packages with higher `priority` values. - -##### Flake descriptors - -Flake descriptors allow installing software from an arbitrary Nix flake. - -The full list of flake descriptor options is: - - Descriptor ::= { - flake = - , systems = null | [, ...] - , priority = null | - } - -Only `flake` is required. `systems` and `priority` behave the same as -described above for catalog descriptors, and `flake` is described below: - -`flake` -Specifies a Nix flake installable, which Nix refers to as a flake output -attribute and documents at -https://nix.dev/manual/nix/2.17/command-ref/new-cli/nix#flake-output-attribute. -Flake installables are of the form `flakeref[#attrpath]`, where flakeref -is a flake reference and attrpath is an optional attribute path. - -Flox tries to use the same fallback behavior as Nix; if no attrpath is -specified, the flake is checked for containing -`packages.$system.default` or `defaultPackage.$system`. If an attrpath -is specified, it is checked whether `packages.$system.$attrpath` or -`legacyPackages.$system.$attrpath` exist. - -### `[vars]` - -The `[vars]` section allows you to define environment variables for your -environment that are set during environment activation. The environment -variables specified here cannot reference one another. The names and -values of the environment variables are copied verbatim into the -activation script, so capitalization will be preserved. - -Example: - -``` toml -[vars] -DB_URL = "http://localhost:2000" -SERVER_PORT = "3000" -``` - -### `[hook]` - -The `on-activate` script in the `[hook]` section is useful for -performing initialization in a predictable Bash shell environment. - -#### `on-activate` - -The `on-activate` script is sourced from a **bash** shell, and it can be -useful for spawning processes, dynamically setting environment -variables, and creating files and directories to be used by the -subsequent profile scripts, commands, and shells. - -Hook scripts inherit environment variables set in the `[vars]` section, -and variables set here will in turn be inherited by the `[profile]` -scripts described below. - -Any output written to `stdout` in a hook script is redirected to -`stderr` to avoid it being mixed with the output of profile section -scripts that write to `stdout` for “in-place” activations. - -``` toml -[hook] -on-activate = """ - # Interact with the tty as you would in any script - echo "Starting up $FLOX_ENV_DESCRIPTION environment ..." - read -e -p "Favourite colour or favorite color? " value - - # Set variables, create files and directories - venv_dir="$(mktemp -d)" - export venv_dir - - # Perform initialization steps, e.g. create a python venv - python -m venv "$venv_dir" - - # Invoke apps that configure the environment via stdout - eval "$(ssh-agent)" -""" -``` - -The `on-activate` script is not re-run when activations are nested. A -nested activation can occur when an environment is already active and -either `eval "$(flox activate)"` or `flox activate -- CMD` is run. In -this scenario, `on-activate` is not re-run. Currently, environment -variables set by the first run of the `on-activate` script are captured -and then later set by the nested activation, but this behavior may -change. - -The `on-activate` script may be re-run by other commands; we may create -ephemeral activations and thus run the script multiple times for -commands such as `services start`. For this reason, it’s best practice -to make `on-activate` idempotent. However, the environment of your -current shell is only affected by the initial run of the script for the -first activation for your shell. - -It’s also best practice to write hooks defensively, assuming the user is -using the environment from any directory on their machine. - -#### `script` - DEPRECATED - -This field was deprecated in favor of the `profile` section. - -### `[profile]` - -Scripts defined in the `[profile]` section are sourced by *your shell* -and inherit environment variables set in the `[vars]` section and by the -`[hook]` scripts. The `profile.common` script is sourced for every -shell, and special care should be taken to ensure compatibility with all -shells, after which exactly one of `profile.{bash,fish,tcsh,zsh}` is -sourced by the corresponding shell. - -These scripts are useful for performing shell-specific customizations -such as setting aliases or configuring the prompt. - -``` toml -[profile] -common = """ - echo "it's gettin' flox in here" -""" -bash = """ - source $venv_dir/bin/activate - alias foo="echo bar" - set -o vi -""" -zsh = """ - source $venv_dir/bin/activate - alias foo="echo bar" - bindkey -v -""" -fish = """ - source $venv_dir/bin/activate.fish - alias foo="echo bar" - fish_vi_key_bindings -""" -``` - -Profile scripts are re-run for nested activations. A nested activation -can occur when an environment is already active and either -`eval "$(flox activate)"` or `flox activate -- CMD` is run. In this -scenario, profile scripts are run a second time. Re-running profile -scripts allows aliases to be set in subshells that inherit from a parent -shell with an already active environment. - -### `[services]` - -The `[services]` section of the manifest allows you to describe the -services you would like to run as part of your environment e.g. a web -server or a database. The services you define here use the packages -provided by the `[install]` section and any variables you’ve defined in -the `[vars]` section or `hook.on-activate` script. - -The `[services]` section is a table of key-value pairs where the keys -determine the service names, and the values (service descriptors) -determine how to configure and run the services. - -An example service definition is shown below: - -``` toml -[services.database] -command = "postgres start" -vars.PGUSER = "myuser" -vars.PGPASSWORD = "super-secret" -vars.PGDATABASE = "mydb" -vars.PGPORT = "9001" -``` - -This would define a service called `database` that configures and starts -a PostgreSQL database. - -The full set of options is show below: - - ServiceDescriptor ::= { - command = STRING - , vars = null | Map[STRING, STRING] - , is-daemon = null | BOOL - , shutdown = null | Shutdown - , systems = null | [, ...] - } - - Shutdown ::= { - command = STRING - } - -`command` -The command to run (interpreted by a Bash shell) to start the service. -This command can use any environment variables that were set in the -`[vars]` section, the `hook.on-activate` script, or the service-specific -`vars` table. - -`vars` -A table of environment variables to set for the invocation of this -specific service. Nothing outside of this service will observe these -environment variables. - -`is-daemon` -Whether this service spawns a daemon when it starts. Some commands start -a background process and then terminate instead of themselves running -for an extended period of time. These programs need special handling -when it comes time to shut down the services, so you must mark them with -the `is-daemon` field. If this field is set to `true` you must also -specify the `shutdown.command` field, otherwise the process will -continue to run after calling `flox services stop` or after exiting the -last activation of the environment. - -`shutdown.command` -A command to run to shut down the service instead of delivering the -SIGTERM signal to the process. Some programs require special handling to -shut down properly e.g. a program that spawns a server process and uses -a client to tell the server to shut down. Sending a SIGTERM to a client -in that case may not shut down the server. In those cases you may -provide a specific shutdown command to run instead of relying on the -default behavior of sending a SIGTERM to the service. This field is -required if the `is-daemon` field is `true`. - -`systems` -An optional list of systems on which to run this service. If omitted, -the service is not restricted. - -### `[options]` - -The `[options]` section of the manifest details settings for the -environment itself. - -The full set of options are listed below: - - Options ::= { - systems = null | [, ...] - , allow = null | Allows - , semver = null | Semver - , cuda-detection = null | - } - - Allows ::= { - unfree = null | - , broken = null | - , licenses = null | [, ...] - } - - Semver ::= { - allow-pre-releases = - } - -`systems` -The allowlist of systems that this environment supports. Valid values -are `x86_64-linux`, `aarch64-linux`, `x86_64-darwin`, and -`aarch64-darwin`. [`flox init`](./flox-init.md) automatically populates -this list with the current system type. A user that attempts to pull an -environment from FloxHub when their environment isn’t explicitly -supported will be prompted whether to automatically add their system to -this list. See [`flox-pull(1)`](./flox-pull.md) for more details. - -`allow.unfree` -Allows packages with unfree licenses to be installed and appear in -search results. The default is `false`. - -`allow.broken` -Allows packages that are marked `broken` in the catalog to be installed -and appear in search results. The default is `false`. - -`allow.licenses` -An allowlist of software licenses to allow in search results in -installs. Valid entries are [SPDX -Identifiers](https://spdx.org/licenses). - -`semver.allow-pre-releases` -Whether to allow pre-release software for package installations. The -default is `false`. Setting this value to `true` would allow a package -version `4.2.0-pre` rather than `4.1.9`. - -`cuda-detection` -Whether to detect CUDA libraries and provide them to the environment. -The default is `true`. When enabled, Flox will detect if you have an -Nvidia device and attempt to locate `libcuda` in well-known paths. Then -it will symlink the libraries into `.flox/lib` and add that path to -`FLOX_ENV_LIB_DIRS`. - -## SEE ALSO - -[`flox-init(1)`](./flox-init.md), -[`flox-install(1)`](./flox-install.md), [`flox-edit(1)`](./flox-edit.md) From 7358a55e5a51fce40ac8e64f55073eae3bc29767 Mon Sep 17 00:00:00 2001 From: Bill LeVine Date: Fri, 10 Apr 2026 12:03:11 -0400 Subject: [PATCH 07/14] fix(lint): add blank lines around fenced code blocks in tools/README.md Co-authored-by: Claude Sonnet 4.6 (1M context) --- tools/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tools/README.md b/tools/README.md index b9405a88..70626a2f 100644 --- a/tools/README.md +++ b/tools/README.md @@ -12,6 +12,7 @@ Generates AI-friendly documentation files from the built MkDocs site: - **`llms-full.txt`** - Full content for RAG systems and answer engines, generated from source Markdown **Usage:** + ```bash python3 tools/generate_llms_txt.py ``` @@ -21,6 +22,7 @@ python3 tools/generate_llms_txt.py Convenience script for local development. Generates both AI files after a MkDocs build. **Usage:** + ```bash mkdocs build ./tools/generate_llms_txt.sh From c4d48a42f42f7b055f4f3e99ce3bf54a4be0db9b Mon Sep 17 00:00:00 2001 From: Bill LeVine Date: Fri, 10 Apr 2026 12:11:23 -0400 Subject: [PATCH 08/14] fix(llms.txt): correct activate syntax, is-daemon key, and typo - Use `flox activate -c` in examples (preferred form per current docs) - Keep `flox activate --` in critical rule (both are valid non-interactive) - Fix `is_daemon` -> `is-daemon` (correct manifest TOML key) - Fix typo: "the you are" -> "you are" Co-authored-by: Claude Sonnet 4.6 (1M context) --- docs/llms.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/llms.txt b/docs/llms.txt index d6d88411..a6a09e1a 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -2,7 +2,7 @@ Flox is a next-generation package manager and environment manager for software development and delivery. It allows for creation of reproducible environments for projects, either through imperative commands or declarative manifests. -If you see a `.flox` directory, that means the you are working with Flox to manage project dependencies and the environment lifecycle. +If you see a `.flox` directory, that means you are working with Flox to manage project dependencies and the environment lifecycle. ## Essential Commands ```bash @@ -12,7 +12,7 @@ flox show # Show package details and versions flox init -d # Initialize Flox environment in a directory flox list -d # List installed packages flox install -d # Install package -flox activate -d -- # Run command in environment +flox activate -d -c # Run command in environment ``` ## Critical Rules for Agentic Usage @@ -45,6 +45,6 @@ To define services, add them to the manifest. Examples: api.command = "go run main.go" # Backend API server frontend.command = "npm run dev" # Frontend dev server mydaemon.command = "mydaemon start" # Daemon that forks -mydaemon.is_daemon = true +mydaemon.is-daemon = true mydaemon.shutdown.command = "mydaemon stop" ``` From 19a640ba0f8cd55e4ec191c1130f2f70176dde60 Mon Sep 17 00:00:00 2001 From: Bill LeVine Date: Fri, 10 Apr 2026 12:13:04 -0400 Subject: [PATCH 09/14] fix(llms.txt): add explicit installation section Adds an Installation section that: - Explicitly calls out that curl|bash and install.flox.dev do not exist - Covers macOS (Homebrew), Debian/Ubuntu (.deb), RPM (.rpm) - Points agents to flox.dev/download for package downloads Co-authored-by: Claude Sonnet 4.6 (1M context) --- docs/llms.txt | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/llms.txt b/docs/llms.txt index a6a09e1a..2ad74570 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -4,6 +4,26 @@ Flox is a next-generation package manager and environment manager for software d If you see a `.flox` directory, that means you are working with Flox to manage project dependencies and the environment lifecycle. +## Installation + +**Do NOT use `curl | bash` or reference `install.flox.dev` — that does not exist.** + +Install Flox from `flox.dev/download` or via a package manager: + +```bash +# macOS +brew install flox + +# Debian/Ubuntu — download .deb from flox.dev/download, then: +sudo apt install /path/to/flox.deb + +# RPM (RedHat/CentOS/Amazon Linux) — download .rpm from flox.dev/download, then: +sudo rpm -ivh /path/to/flox.rpm + +# Verify installation +flox --version +``` + ## Essential Commands ```bash flox envs # See which environments are active From f562263a374b0e828ec0577b6102de731e5d44e9 Mon Sep 17 00:00:00 2001 From: Bill LeVine Date: Fri, 10 Apr 2026 12:22:07 -0400 Subject: [PATCH 10/14] fix(llms-full): substitute MkDocs template vars before writing Raw source markdown contains {{ FLOX_VERSION }} and {{ FLOX_PUBLIC_KEY }} placeholders that MkDocs resolves during build. When concatenated directly, these produce invalid URLs (e.g. download links truncated at 'flox-') that fail link checking. Read FLOX_VERSION from environment (set by flox activate hook) and hardcode FLOX_PUBLIC_KEY (static value from mkdocs.yml) to produce valid resolved content in llms-full.txt. Co-authored-by: Claude Sonnet 4.6 (1M context) --- tools/generate_llms_txt.py | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/tools/generate_llms_txt.py b/tools/generate_llms_txt.py index 06a24dc3..00224417 100755 --- a/tools/generate_llms_txt.py +++ b/tools/generate_llms_txt.py @@ -322,9 +322,21 @@ def generate_llms_txt(site_dir: Path, output_path: Path): def generate_llms_full(docs_dir: Path, output_path: Path): - """Generate llms-full.txt from source Markdown files.""" + """Generate llms-full.txt from source Markdown files. + + Substitutes MkDocs template variables so that URLs and version + references are valid in the output (e.g. download links). + """ md_files = sorted(docs_dir.rglob("*.md")) + # Read template variables from mkdocs.yml and environment + flox_version = os.environ.get('FLOX_VERSION', '') + flox_public_key = 'flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs=' + substitutions = { + '{{ FLOX_VERSION }}': flox_version, + '{{ FLOX_PUBLIC_KEY }}': flox_public_key, + } + with open(output_path, 'w') as f: f.write("# Flox Documentation — Full Content\n\n") f.write("Complete documentation for RAG systems and Cursor @Docs.\n\n") @@ -332,7 +344,10 @@ def generate_llms_full(docs_dir: Path, output_path: Path): for md_file in md_files: rel = md_file.relative_to(docs_dir) f.write(f"\n\n---\n\n## {rel}\n\n") - f.write(md_file.read_text(encoding='utf-8')) + content = md_file.read_text(encoding='utf-8') + for placeholder, value in substitutions.items(): + content = content.replace(placeholder, value) + f.write(content) print(f"Generated {output_path} from {len(md_files)} source files") From fb5d98bb6c87c88c999f5e720a8c433be71815f7 Mon Sep 17 00:00:00 2001 From: Bill LeVine Date: Fri, 10 Apr 2026 12:22:55 -0400 Subject: [PATCH 11/14] fix(ci): exclude localhost and cluster-local URLs from link checker MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit These are example URLs in code blocks (manifest env var examples, k8s config examples) — not real links. Add broad exclusions so they are skipped regardless of which file lychee scans. Co-authored-by: Claude Sonnet 4.6 (1M context) --- lychee.toml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lychee.toml b/lychee.toml index 4ad5d078..84afaf03 100644 --- a/lychee.toml +++ b/lychee.toml @@ -10,6 +10,8 @@ host_request_interval = "500ms" exclude = [ '^javascript:', '^data:', + '^http://localhost', + '\.svc\.cluster\.local', 'bash/manual/html_node', 'https://www\.gnu\.org/software/make/', 'https://github\.com/flox/catalog-util', From b960fac2590e6de2ef302249fa73204c3fb287f3 Mon Sep 17 00:00:00 2001 From: Bill LeVine Date: Fri, 10 Apr 2026 12:29:47 -0400 Subject: [PATCH 12/14] fix(ci): exclude code-block example URLs from link checker - auth.flox.dev/oauth/token: POST-only OAuth endpoint, GET returns 404 by design; appears in curl example in organizations.md - nix.dev/manual/nix/2.17/: versioned nix docs anchor referenced in manifest.toml docs; surfaced by llms-full.txt plain-text scanning These URLs are in code block examples and not meant to be navigated. Lychee skips them in HTML but treats them as links in plain text. Co-authored-by: Claude Sonnet 4.6 (1M context) --- lychee.toml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lychee.toml b/lychee.toml index 84afaf03..31682bcb 100644 --- a/lychee.toml +++ b/lychee.toml @@ -12,6 +12,8 @@ exclude = [ '^data:', '^http://localhost', '\.svc\.cluster\.local', + 'https://auth\.flox\.dev/oauth/token', + 'https://nix\.dev/manual/nix/2\.17/', 'bash/manual/html_node', 'https://www\.gnu\.org/software/make/', 'https://github\.com/flox/catalog-util', From a48859ab31ad5c6d252efb59e767143d879a7afa Mon Sep 17 00:00:00 2001 From: Bill LeVine Date: Fri, 10 Apr 2026 12:45:02 -0400 Subject: [PATCH 13/14] fix(ci): exclude CDN root and yum repo URL from link checker - cache.flox.dev root: Nix binary cache CDN, root returns 404 but the service is valid; appears in nix.conf code block examples - downloads.flox.dev/by-env/stable/rpm: yum repo URL in installing-from-repo.md, not a web page; directory returns 404 Co-authored-by: Claude Sonnet 4.6 (1M context) --- lychee.toml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lychee.toml b/lychee.toml index 31682bcb..2f1b69c4 100644 --- a/lychee.toml +++ b/lychee.toml @@ -14,6 +14,8 @@ exclude = [ '\.svc\.cluster\.local', 'https://auth\.flox\.dev/oauth/token', 'https://nix\.dev/manual/nix/2\.17/', + '^https://cache\.flox\.dev/?$', + 'downloads\.flox\.dev/by-env/stable/rpm$', 'bash/manual/html_node', 'https://www\.gnu\.org/software/make/', 'https://github\.com/flox/catalog-util', From 7f7f2f7573ea34eaf582f9d5528b4770e877876c Mon Sep 17 00:00:00 2001 From: Bill LeVine Date: Fri, 10 Apr 2026 13:11:45 -0400 Subject: [PATCH 14/14] fix(llms.txt): document both non-interactive activate forms Both -c and -- are valid but behave differently: - -c: subshell with full hooks/profile (preferred for agents) - --: exec mode, no profile scripts Co-authored-by: Claude Sonnet 4.6 (1M context) --- docs/llms.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/llms.txt b/docs/llms.txt index 2ad74570..580857a1 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -36,7 +36,9 @@ flox activate -d -c # Run command in environment ``` ## Critical Rules for Agentic Usage -1. **NEVER run `flox activate` interactively** - use `flox activate -- ` +1. **NEVER run `flox activate` interactively** — two non-interactive forms: + - `flox activate -c ` — runs in a subshell with full hooks and profile scripts (preferred for agents) + - `flox activate -- ` — exec mode, replaces the shell process, profile scripts do not run 2. **ALWAYS use `flox install`** instead of apt/yum/rpm/brew 3. Edit `.flox/env/manifest.toml` directly (not using `flox edit`)