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>--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>--</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>
# nixos-enter /mnt
</screen>

<para>Run a shell command:</para>

<screen>
# 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>