.. _tutorials-onboarding-m1-linux-commands:

Essential Linux Commands
========================

Interacting with the CoSTAR cluster happens mostly via a text-based Linux terminal.
If you are new to this environment, we suggest you review the `Surrey Unix Tutorial for Beginners <https://info-ee.surrey.ac.uk/Teaching/Unix/>`__.


Use the tabs below to find common commands categorised by workflow, along with specific examples of how they apply to cluster tasks.

.. tab-set::

   .. tab-item:: 📁 Navigation & Files

      .. list-table::
         :widths: 25 35 40
         :header-rows: 1
         :class: sd-table-hover

         * - Command
           - What it does
           - HPC Example / Context
         * - ``pwd``
           - Print Working Directory. Shows where you are.
           - Check if you are in ``/users/your_name`` or a parallel path.
         * - ``ls -lh``
           - Lists directory contents with human-readable file sizes.
           - ``ls -lh`` reveals if a dataset or model weight file downloaded completely.
         * - ``cd <path>``
           - Change Directory. Moves you to a new folder.
           - ``cd /parallel_scratch/project_name`` jumps to shared storage.
         * - ``mkdir -p <name>``
           - Creates a new directory (and parent folders if missing).
           - ``mkdir -p checks/run_01`` sets up clean output spaces.
         * - ``cp -r <src> <dst>``
           - Copies files or directories recursively.
           - Copy a template batch script into your working workspace.
         * - ``mv <src> <dst>``
           - Moves or renames files and directories.
           - Rename a generic checkpoint file to a specific iteration name.
         * - ``rm -rf <target>``
           - Forcefully and recursively deletes files/folders.
           - **Use with extreme caution.** Erases directories without prompting.

   .. tab-item:: 🔍 Viewing & Searching

      .. list-table::
         :widths: 25 35 40
         :header-rows: 1
         :class: sd-table-hover

         * - Command
           - What it does
           - HPC Example / Context
         * - ``cat <file>``
           - Dumps the entire contents of a file directly into the terminal.
           - Good for quickly verifying a short, 10-line Slurm batch script.
         * - ``less <file>``
           - Opens a scrollable reader. Press ``q`` to exit.
           - Use this to inspect large execution logs without crashing your terminal.
         * - ``tail -n 20 <file>``
           - Displays the final 20 lines of a file.
           - Quickly check if a completed job threw an error at the very end.
         * - ``tail -f <file>``
           - Displays the end of a file and **updates in real-time** as lines are added.
           - Run ``tail -f slurm-12345.out`` to watch live script printouts as your AI model trains.
         * - ``grep "pattern" <file>``
           - Searches inside text files for specific strings or phrases.
           - ``grep "Loss:" slurm-*.out`` instantly extracts training loss metrics.
         * - ``nano <file>``
           - A simple, straightforward command-line text editor.
           - Great for quick, live modifications to your Slurm option flags.

   .. tab-item:: 🛠️ Permissions & Diagnostics

      .. list-table::
         :widths: 25 35 40
         :header-rows: 1
         :class: sd-table-hover

         * - Command
           - What it does
           - HPC Example / Context
         * - ``chmod +x <file>``
           - Marks a file as **executable**.
           - Run ``chmod +x script.sh`` before executing a file via ``./script.sh``, or it will fail to launch.
         * - ``du -sh <target>``
           - Summarises the total disk space used by a file or folder.
           - ``du -sh *`` identifies which hidden directory is filling up your 30GB home space.
         * - ``watch -n 2 <cmd>``
           - Runs a command repeatedly every ``n`` seconds, showing changes live.
           - ``watch -n 5 squeue -u $USER`` monitors your queue position automatically without re-typing.
         * - ``<cmd> --help``
           - Appending help flags lists usage manuals for custom tools.
           - Useful for investigating deep tools like ``apptainer --help`` or ``sacctmgr --help``.



Next Steps
----------

.. grid:: 1 2 2 2
   :gutter: 3
   :margin: 1


   .. grid-item-card:: :octicon:`checklist` 1.5 Self-Check Quiz
      :link: tutorials-onboarding-m1-quiz
      :link-type: ref
      :class-card: sd-outline-success

      Test your understanding of the introductory material before moving to Module 2.