.. _canopy_cli: Canopy Command Line Interface (CLI) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ *If, like most users, you do not share a machine and want the ability to use both the Canopy GUI and the command line, then you probably do not need to use the Canopy Command Line Interface (CLI).* The Canopy CLI is primarily intended for use in multi-user or command-line-only (non-GUI) configurations, by users comfortable working at the system command prompt. In particular, it is useful for administrators writing automation scripts for Canopy, such as for cluster deployments. This section covers :ref:`details of the CLI`, :ref:`installation of Canopy via the command line in a non-GUI environment`, and :ref:`configuring Canopy for use in a multi-user environment`. .. note:: Canopy before version 2.0 used layered virtual environments for its User Python environments. Canopy 2.0 no longer supports these legacy virtual environments. All newly created User Python environments in Canopy 2.0 and above are non-virtual, single-layer, self-contained Python environments. Therefore, the CLI options for working with virtual environments are removed in Canopy 2.0. For information about these options, please see the `documentation for Canopy 1.7.4 `_. Canopy 2.0 uses the Enthought Deployment Manager (EDM) to create and manage all new User Python environments. See the `EDM documentation `_ for details about EDM's CLI, which can be used to manage new Canopy User Python environments from the command line. .. _command_line_interface: Command line interface ====================== The Canopy Command Line Interface (CLI) is available via the ``canopy_cli`` command, available both in the Canopy application installation, and in the Canopy User Python environment. The tables at the end of this sub-section list the default install paths for the Canopy CLI, on each operating system. The ``canopy_cli`` command has the following sub-command structure: :: canopy_cli [] [options] [positional arguments] The following table shows the available sub-commands and their options and arguments. =========================== =========================================================== Function Sub-command usage =========================== =========================================================== Create a common install post-install-setup [-h] =========================== =========================================================== The CLI can also be run with no sub-command, as described below in these sections: | :ref:`cmd_line_setup` Canopy CLI's default location in the Canopy Application ------------------------------------------------------- ===================== ======= =================================================================== Platform Version Location ===================== ======= =================================================================== Windows 7 and above 64 ``C:\Users\\AppData\Local\Enthought\Canopy\App\Canopy_cli.exe`` Windows 7 and above 32 ``C:\Users\\AppData\Local\Enthought\Canopy32\App\Canopy_cli.exe`` Mac OS X 64 ``/Applications/Canopy.app/Contents/MacOS/Canopy_cli`` Linux 64 ``~/Canopy/canopy_cli`` ===================== ======= =================================================================== Canopy CLI's default location in the Canopy User Python environment ------------------------------------------------------------------- ===================== ======= =================================================================== Platform Version Location ===================== ======= =================================================================== Windows 7 and above 64 ``C:\Users\\AppData\Local\Enthought\Canopy\edm\envs\User\Scripts\canopy_cli.exe`` Windows 7 and above 32 ``C:\Users\\AppData\Local\Enthought\Canopy32\edm\envs\User\Scripts\canopy_cli.exe`` Mac OS X 64 ``~/Library/Enthought/Canopy/edm/envs/User/bin/canopy_cli`` Linux 64 ``~/.local/share/canopy/edm/envs/User/bin/canopy_cli`` ===================== ======= =================================================================== .. _cmd_line_setup: Scenario: Setting up the User environment without a setup GUI ============================================================= Normally, when Canopy is launched for the first time by clicking on its icon, it will set up the user's Python environment, and perhaps pop up dialog windows with questions. However, when you remotely connect to the machine via a text-only interface such as ssh, the GUI application will not normally start. In such a scenario, you can perform the environment setup without a GUI, by using the CLI ``post-install-setup --setup-user-env`` option: ============== ====================================================================== Platform Commmand ============== ====================================================================== Windows ``C:\Users\\AppData\Local\Enthought\Canopy\edm\envs\User\Scripts\canopy_cli.exe post-install-setup --setup-user-env`` Mac OS X ``/Applications/Canopy.app/Contents/MacOS/Canopy_cli post-install-setup --setup-user-env`` Linux ``~/Canopy/canopy_cli post-install-setup --setup-user-env`` ============== ====================================================================== The user's Python environment will be created in the same default directory as if Canopy had been launched with a normal GUI dialog (:ref:`venv_where_are_packages`). If you are a Canopy premium support subscriber, and need to change the location of the user's Python environment, please contact Enthought Support for instructions. Note about file permissions on Mac and Linux -------------------------------------------- The setup commands shown above should generally be run as an admin user, but not as the root user, i.e. not using default ``sudo``. You would need to ensure that the admin user has write access, and that all ordinary users have read and execute access, to the target directory (``/usr/local/Canopy`` in this example, or whatever target directory you choose). Scenario: Update canopy and edm entry points ============================================ The Canopy (i.e. ``canopy`` and ``canopy_cli``) and EDM entry points (i.e. ``edm``), that are found in each Canopy-managed python environment, depend on the position of the Canopy installation folder. This means that on upgrading canopy these entry points might become invalid. The check and update will normally happen on Canopy GUI start-up, but when running the Canopy GUI application this is not possible, so the post-install-setup subcommand allows you to manually update the entry-points, by using the CLI ``post-install-setup --fix-scripts`` option: ============== ====================================================================== Platform Commmand ============== ====================================================================== Windows ``C:\Users\\AppData\Local\Enthought\Canopy\edm\envs\User\Scripts\canopy_cli.exe post-install-setup --fix-scripts`` Mac OS X ``/Applications/Canopy.app/Contents/MacOS/Canopy_cli post-install-setup --fix-scripts`` Linux ``~/Canopy/canopy_cli post-install-setup --fix-scripts`` ============== ====================================================================== .. note:: The ``--fix-scripts`` option should only be used from a command line terminal when calling the canopy_cli directly from the Canopy application install folder. Using the ``--fix-scripts`` option inside a Canopy command prompt terminal will fail. .. _sys_wide_canopy_install: Scenario: Canopy Managed Common Install ======================================= Canopy v2 supports a *Managed Common Install* that provides all users with the same set of Python environments, managed by system administration. This is well suited to production environments, classrooms, and other institutions that wish to ensure a uniform set of centrally managed packages for all users. For more info on the advantages and limitations of this configuration, please read the Knowledge Base article `"Canopy 2 Managed Common Install" `_. .. note:: Canopy 1.6 and 1.7 supported a *common install* setup, using virtual environments inheriting from a shared central environment.. For more information please read the Knowledge Base article `"Canopy 1.6 and 1.7 Common Install Options" `_. .. rubric:: Setup On an windows command line (i.e. ``cmd.exe``) shell, with administrator privileges, install canopy using the following:: msiexec.exe /l*vm install.log /i "" /qr SETUP_MANAGED_COMMON_INSTALL="" ALLUSERS=1 ``SETUP_MANAGED_COMMON_INSTALL`` -- The path where the Canopy managed python environments are stored. Normal users are expected to have permission to read and execute files in this folder. ``ALLUSERS=1`` -- The canopy application will be installed in ``Program Files`` (or ``Program files (x86)`` when using Canopy32). After installation each user should be able to launch Canopy from the Windows Start menu. The Canopy application should be able to switch between the available environments that the system administrator has set up. .. rubric:: Manage shared environments To start a maintenance session the administrator needs to set up the managed EDM environments to allow changes and toggle them back when finished. This is achieved using the canopy cli tool with the `edm` subcommand and the ``mark-read-write``, ``mark-read-only`` directives: ============== ====================================================================== Platform Commmand ============== ====================================================================== Windows ``C:\Users\\AppData\Local\Enthought\Canopy\edm\envs\User\Scripts\canopy_cli.exe edm `` Mac OS X ``/Applications/Canopy.app/Contents/MacOS/Canopy_cli edm `` Linux ``~/Canopy/canopy_cli edm `` ============== ====================================================================== :: edm mark-read-write # ... enable edm environment maintenance operations through the Canopy # ... Command Prompt and the Canopy Package Manager. edm mark-read-only # ... disable such operations. Once EDM python environments have been marked as *read/write* the administrator should be able to start Canopy and use the Canopy Package Manager or the :ref:`canopy_terminal`. .. warning:: - All maintenance operations normally will require administrative privileges. In Windows, this will typically require starting Canopy "As Administrator". - It is important that the `edm mark-read-only` subcommand be issued as soon as the maintenance session is finished. - Users should not run Canopy or use any of the Canopy-managed Python environments during maintenance operations. For changes, troubleshooting, use-cases and advanced uses of *managed common install* please refer to `"Canopy 2 Managed Common Install" `_.