Add commands

Author: SimonSchubert

assets/commands/3d-ascii-viewer.md

@@ -0,0 +1,93 @@
+# TLDR
+
+**View a 3D model** as ASCII art in the terminal
+
+```3d-ascii-viewer [path/to/model.obj]```
+
+**View with specific dimensions**
+
+```3d-ascii-viewer -w [80] -h [40] [model.obj]```
+
+**Render with colored output**
+
+```3d-ascii-viewer --color [model.obj]```
+
+**View STL file** with rotation
+
+```3d-ascii-viewer --rotate-x [45] --rotate-y [30] [model.stl]```
+
+**Set custom ASCII characters** for shading
+
+```3d-ascii-viewer --charset " .:-=+*#%@" [model.obj]```
+
+**Enable wireframe mode**
+
+```3d-ascii-viewer --wireframe [model.obj]```
+
+**Output to file** instead of terminal
+
+```3d-ascii-viewer [model.obj] > [output.txt]```
+
+# SYNOPSIS
+
+**3d-ascii-viewer** [_options_] _model_file_
+
+# PARAMETERS
+
+**-w**, **--width** _n_
+> Set output width in characters.
+
+**-h**, **--height** _n_
+> Set output height in characters.
+
+**--color**
+> Enable colored ASCII output using ANSI codes.
+
+**--rotate-x** _degrees_
+> Rotate model around the X axis.
+
+**--rotate-y** _degrees_
+> Rotate model around the Y axis.
+
+**--rotate-z** _degrees_
+> Rotate model around the Z axis.
+
+**--wireframe**
+> Render as wireframe instead of solid.
+
+**--charset** _chars_
+> Custom characters for brightness levels (dark to light).
+
+**--scale** _factor_
+> Scale the model by the specified factor.
+
+**--fps** _n_
+> Frames per second for animation mode.
+
+**--animate**
+> Continuously rotate the model.
+
+**--help**
+> Display help information.
+
+# DESCRIPTION
+
+**3d-ascii-viewer** renders 3D model files as ASCII art in the terminal. It converts 3D geometry into text-based representations using characters of varying density to simulate shading and depth.
+
+The tool supports common 3D formats including OBJ and STL files. Models are rendered using a simple rasterization approach where surface brightness determines which ASCII character is used. Darker areas use sparse characters like dots while brighter areas use dense characters like @ or #.
+
+For interactive exploration, the animate mode continuously rotates the model, creating a spinning effect in the terminal. The color mode adds ANSI color codes for enhanced visual output on terminals that support them.
+
+Output dimensions default to the terminal size but can be overridden for specific use cases like generating ASCII art for text files or documentation. The tool is useful for quick model inspection without launching a full 3D viewer.
+
+# CAVEATS
+
+Complex models with many polygons may render slowly or lose detail. Terminal font and aspect ratio affect the visual output. Color support depends on terminal capabilities. Very small output dimensions may produce unrecognizable results.
+
+# HISTORY
+
+ASCII art renderers for 3D content emerged alongside the demoscene and terminal art communities. Various implementations exist across programming languages, with modern versions supporting standard 3D file formats. The technique builds on decades of ASCII art tradition dating back to early computing.
+
+# SEE ALSO
+
+[meshlab](/man/meshlab)(1), [openscad](/man/openscad)(1), [blender](/man/blender)(1), [figlet](/man/figlet)(1)

assets/commands/alembic.md

@@ -0,0 +1,109 @@
+# TLDR
+
+**Initialize Alembic** in a project
+
+```alembic init [alembic]```
+
+**Create a new migration** revision
+
+```alembic revision -m "[Add users table]"```
+
+**Auto-generate a migration** from model changes
+
+```alembic revision --autogenerate -m "[Add email column]"```
+
+**Upgrade to the latest** migration
+
+```alembic upgrade head```
+
+**Upgrade to a specific revision**
+
+```alembic upgrade [revision_id]```
+
+**Downgrade by one revision**
+
+```alembic downgrade -1```
+
+**Show current revision**
+
+```alembic current```
+
+**Display migration history**
+
+```alembic history```
+
+# SYNOPSIS
+
+**alembic** [_options_] _command_ [_command_options_]
+
+# PARAMETERS
+
+**init** _directory_
+> Initialize a new Alembic environment in the specified directory.
+
+**revision** [_-m message_] [_--autogenerate_]
+> Create a new migration revision file.
+
+**upgrade** _revision_
+> Upgrade database to a target revision (use 'head' for latest).
+
+**downgrade** _revision_
+> Downgrade database to a target revision (use '-1' for one step back).
+
+**current**
+> Show the current revision of the database.
+
+**history**
+> List revision history.
+
+**heads**
+> Show all current head revisions.
+
+**branches**
+> Show all branch points.
+
+**stamp** _revision_
+> Set the revision table to a specific version without running migrations.
+
+**show** _revision_
+> Display details of a specific revision.
+
+**merge** _revisions_ [_-m message_]
+> Merge multiple branch heads into one.
+
+**-c**, **--config** _file_
+> Path to alembic.ini configuration file.
+
+**-n**, **--name** _name_
+> Name of config section to use.
+
+**-x** _key=value_
+> Pass additional arguments to env.py.
+
+**--autogenerate**
+> Auto-generate migration by comparing models to database.
+
+**--sql**
+> Output SQL instead of applying migrations.
+
+# DESCRIPTION
+
+**Alembic** is a database migration tool for SQLAlchemy, Python's popular ORM. It manages incremental, reversible changes to database schemas through version-controlled migration scripts.
+
+Migrations are Python files stored in a versions directory. Each migration has an upgrade() function to apply changes and a downgrade() function to reverse them. Alembic tracks the current database state in a special table, allowing it to determine which migrations need to run.
+
+The **--autogenerate** feature compares SQLAlchemy model definitions against the current database schema to automatically generate migration scripts. While convenient, generated migrations should be reviewed as autogenerate cannot detect all types of changes.
+
+Configuration is stored in **alembic.ini**, which specifies the database URL, migration script location, and other settings. The **env.py** script in the alembic directory handles migration environment setup and can be customized for complex scenarios.
+
+# CAVEATS
+
+Autogenerate cannot detect all changes (table renames, column type changes on some databases, constraint name changes). Always review generated migrations. Downgrade functions must be manually written or verified for autogenerated migrations. Database URL in alembic.ini may contain credentials that should not be committed.
+
+# HISTORY
+
+**Alembic** was created by Mike Bayer, the author of SQLAlchemy, with the first release in **2011**. It was designed to provide a migration solution that integrates naturally with SQLAlchemy's metadata and model system. The name comes from the alchemical vessel used for distillation, fitting the SQLAlchemy naming theme.
+
+# SEE ALSO
+
+[flask-migrate](/man/flask-migrate)(1), [django-admin](/man/django-admin)(1), [sqlalchemy](/man/sqlalchemy)(1), [psql](/man/psql)(1)

assets/commands/apptainer-exec.md

@@ -0,0 +1,109 @@
+# TLDR
+
+**Execute a command** inside a container
+
+```apptainer exec [container.sif] [command]```
+
+**Run with bound directory** from host to container
+
+```apptainer exec --bind [/host/path]:[/container/path] [container.sif] [command]```
+
+**Execute with writable overlay**
+
+```apptainer exec --overlay [overlay.img] [container.sif] [command]```
+
+**Run with GPU support** (NVIDIA)
+
+```apptainer exec --nv [container.sif] [command]```
+
+**Execute from Docker Hub** image
+
+```apptainer exec docker://[ubuntu:latest] [cat /etc/os-release]```
+
+**Run with isolated network**
+
+```apptainer exec --net --network none [container.sif] [command]```
+
+**Execute with custom environment variable**
+
+```apptainer exec --env [VAR=value] [container.sif] [command]```
+
+**Run with all host filesystems bound**
+
+```apptainer exec --bind /:/host:ro [container.sif] [command]```
+
+# SYNOPSIS
+
+**apptainer exec** [_options_] _container_ _command_ [_args_]
+
+# PARAMETERS
+
+**--bind**, **-B** _src[:dest[:opts]]_
+> Bind mount a path from the host into the container.
+
+**--overlay** _image_
+> Use an overlay filesystem for writable layer.
+
+**--nv**
+> Enable NVIDIA GPU support inside the container.
+
+**--rocm**
+> Enable AMD ROCm GPU support.
+
+**--contain**, **-c**
+> Use minimal /dev and empty other directories.
+
+**--containall**, **-C**
+> Full isolation: contain plus clean environment and no PID namespace.
+
+**--cleanenv**, **-e**
+> Clean environment before running container.
+
+**--env** _VAR=value_
+> Set environment variable in container.
+
+**--env-file** _file_
+> Load environment variables from file.
+
+**--home** _path_
+> Set custom home directory.
+
+**--pwd** _path_
+> Set initial working directory in container.
+
+**--net**
+> Enable network namespace.
+
+**--network** _type_
+> Specify network type (none, bridge, etc.).
+
+**--fakeroot**
+> Run container with fake root privileges.
+
+**--writable-tmpfs**
+> Add writable tmpfs overlay.
+
+**--no-mount** _type_
+> Disable specific mount (proc, sys, dev, devpts, home, tmp, cwd).
+
+# DESCRIPTION
+
+**apptainer exec** runs a specified command inside an Apptainer container. Unlike **apptainer shell** which provides an interactive session, exec runs a single command and returns its exit status, making it ideal for batch processing and scripts.
+
+The container can be specified as a local SIF file, a library URI (library://), a Docker URI (docker://), or an OCI archive. The command and any arguments are executed within the container environment with the current user's identity preserved.
+
+By default, Apptainer mounts the current directory, home directory, and standard system paths into the container. Additional paths can be bound using **--bind**. For HPC workloads, the **--nv** or **--rocm** flags enable GPU passthrough.
+
+The command inherits the host's environment by default. Use **--cleanenv** for reproducibility or **--contain** for isolation. Exit status reflects the executed command's return code.
+
+# CAVEATS
+
+User namespaces must be enabled in the kernel for rootless operation. Some containers may require **--writable-tmpfs** or **--overlay** to function properly. NVIDIA GPU support requires the nvidia-container-cli and compatible drivers. Network namespace requires root or appropriate privileges unless user namespaces are configured.
+
+# HISTORY
+
+Apptainer is the continuation of the **Singularity** project after it joined the Linux Foundation in **2021**. The exec subcommand has been a core feature since Singularity's inception at Lawrence Berkeley National Laboratory in **2015**. Apptainer 1.0 was released in **2022**, maintaining full compatibility with Singularity container formats while adding new features.
+
+# SEE ALSO
+
+[apptainer](/man/apptainer)(1), [apptainer-shell](/man/apptainer-shell)(1), [apptainer-run](/man/apptainer-run)(1), [apptainer-build](/man/apptainer-build)(1), [docker](/man/docker)(1)

assets/commands/apptainer-run-help.md

@@ -0,0 +1,51 @@
+# TLDR
+
+**Display the run-help** for a container
+
+```apptainer run-help [container.sif]```
+
+**Show help for a Docker Hub image**
+
+```apptainer run-help docker://[image:tag]```
+
+**Display help from a library image**
+
+```apptainer run-help library://[user/collection/image:tag]```
+
+**Get run-help for an OCI archive**
+
+```apptainer run-help oci-archive://[path/to/archive.tar]```
+
+# SYNOPSIS
+
+**apptainer run-help** [_options_] _container_
+
+# PARAMETERS
+
+_container_
+> Path to a SIF file or URI to a container image (docker://, library://, oci-archive://).
+
+**--help**, **-h**
+> Display help for the run-help command.
+
+# DESCRIPTION
+
+**apptainer run-help** displays help text embedded within an Apptainer/Singularity container. This help information is defined during container build time using the **%help** section in a definition file.
+
+Container authors use the %help section to document how to use their container, including expected arguments, required bind mounts, environment variables, and example commands. This provides users with container-specific usage information without needing external documentation.
+
+When called on a container without a help section, the command returns with no output. The help text is stored in the container's metadata and does not affect the container's runtime size significantly.
+
+This command is particularly useful in HPC environments where users may encounter unfamiliar containers and need quick usage guidance. It complements **apptainer inspect** which shows technical metadata rather than user-facing documentation.
+
+# CAVEATS
+
+Only displays help if the container author included a %help section during build. Returns nothing (not an error) if no help is defined. Cannot add help to an existing container without rebuilding it.
+
+# HISTORY
+
+The run-help feature has been part of Singularity/Apptainer since early versions, providing a standardized way for container authors to document container usage. The command was retained when Singularity became Apptainer under the Linux Foundation in **2021**.
+
+# SEE ALSO
+
+[apptainer](/man/apptainer)(1), [apptainer-run](/man/apptainer-run)(1), [apptainer-inspect](/man/apptainer-inspect)(1), [apptainer-build](/man/apptainer-build)(1)