path: root/nixos/doc/manual/man-nixos-enter.xml

<refentry xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:xi="http://www.w3.org/2001/XInclude">
 <refmeta>
  <refentrytitle><command>nixos-enter</command>
  </refentrytitle><manvolnum>8</manvolnum>
  <refmiscinfo class="source">NixOS</refmiscinfo>
<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
 </refmeta>
 <refnamediv>
  <refname><command>nixos-enter</command></refname>
  <refpurpose>run a command in a NixOS chroot environment</refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <cmdsynopsis>
   <command>nixos-enter</command>
   <arg>
    <arg choice='plain'>
     <option>--root</option>
    </arg>
     <replaceable>root</replaceable>
   </arg>

   <arg>
    <arg choice='plain'>
     <option>--system</option>
    </arg>
     <replaceable>system</replaceable>
   </arg>

   <arg>
    <arg choice='plain'>
     <option>-c</option>
    </arg>
     <replaceable>shell-command</replaceable>
   </arg>

   <arg>
    <arg choice='plain'>
     <option>--silent</option>
    </arg>
   </arg>

   <arg>
    <arg choice='plain'>
     <option>--help</option>
    </arg>
   </arg>

   <arg>
    <arg choice='plain'>
     <option>--</option>
    </arg>
     <replaceable>arguments</replaceable>
   </arg>
  </cmdsynopsis>
 </refsynopsisdiv>
 <refsection>
  <title>Description</title>
  <para>
   This command runs a command in a NixOS chroot environment, that is, in a
   filesystem hierarchy previously prepared using
   <command>nixos-install</command>.
  </para>
 </refsection>
 <refsection>
  <title>Options</title>
  <para>
   This command accepts the following options:
  </para>
  <variablelist>
   <varlistentry>
    <term>
     <option>--root</option>
    </term>
    <listitem>
     <para>
      The path to the NixOS system you want to enter. It defaults to
      <filename>/mnt</filename>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--system</option>
    </term>
    <listitem>
     <para>
      The NixOS system configuration to use. It defaults to
      <filename>/nix/var/nix/profiles/system</filename>. You can enter a
      previous NixOS configuration by specifying a path such as
      <filename>/nix/var/nix/profiles/system-106-link</filename>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--command</option>
    </term>
    <term>
     <option>-c</option>
    </term>
    <listitem>
     <para>
      The bash command to execute.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--silent</option>
    </term>
    <listitem>
     <para>
       Suppresses all output from the activation script of the target system.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--</option>
    </term>
    <listitem>
     <para>
      Interpret the remaining arguments as the program name and arguments to be
      invoked. The program is not executed in a shell.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsection>
 <refsection>
  <title>Examples</title>
  <para>
   Start an interactive shell in the NixOS installation in
   <filename>/mnt</filename>:
  </para>
<screen>
<prompt># </prompt>nixos-enter --root /mnt
</screen>
  <para>
   Run a shell command:
  </para>
<screen>
<prompt># </prompt>nixos-enter -c 'ls -l /; cat /proc/mounts'
</screen>
  <para>
   Run a non-shell command:
  </para>
<screen>
# nixos-enter -- cat /proc/mounts
</screen>
 </refsection>
</refentry>