Yazelix Nova

https://github.com/yazelix/nova
Admin
Yazelix Nova is a Nix-packaged terminal workspace that integrates Rio, Zellij, Helix, Yazi, and...
Tokens:13,497
Snippets:211
Trust Score:6
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Inspect runtime setup

Source: https://github.com/yazelix/nova/blob/main/README.md

Run the doctor command to diagnose issues with the owned runtime setup.

```sh
nix run github:Yazelix/nova/stable -- doctor
```

--------------------------------

### Launch Yazelix Guided Tour

Source: https://github.com/yazelix/nova/blob/main/README.md

Initiates the interactive tutorial for new users.

```sh
yzx tutor begin
```

--------------------------------

### Install temporary profile

Source: https://github.com/yazelix/nova/blob/main/docs/development.md

Command to test runtime package changes by installing to a temporary profile.

```sh
nix profile add --refresh /absolute/path/to/yazelix --profile /tmp/yzx-profile
```

--------------------------------

### Install in a Nix profile

Source: https://github.com/yazelix/nova/blob/main/README.md

Add the stable version to the current Nix profile for persistent access.

```sh
nix profile add --refresh github:Yazelix/nova/stable
yzx launch
```

--------------------------------

### Install Yazi Flavors via CLI

Source: https://github.com/yazelix/nova/blob/main/docs/configuration.md

Use the Yazi package manager to install community flavors into the managed configuration directory.

```sh
config_home="${YAZELIX_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/yazelix}"
mkdir -p "$config_home/yazi"
YAZI_CONFIG_HOME="$config_home/yazi" \
  yzx run ya pkg add yazi-rs/flavors:catppuccin-mocha
```

--------------------------------

### Zellij Plugin Declarations

Source: https://github.com/yazelix/nova/blob/main/docs/runtime-notes.md

Example structure for defining extra plugins and loading them in zellij/plugins.kdl.

```kdl
plugins {
    my_plugin location="file:/home/me/.config/zellij/plugins/my_plugin.wasm"
}

load_plugins {
    my_plugin
}
```

--------------------------------

### Upgrade installed runtime

Source: https://github.com/yazelix/nova/blob/main/.agent-protocols.local.md

Updates the user's installed runtime to the latest version.

```sh
nix profile upgrade --refresh yazelix
```

--------------------------------

### Install Nova package variants via Nix

Source: https://github.com/yazelix/nova/blob/main/docs/installation.md

Use these commands to install specific Nova variants. Ensure the appropriate dependencies are available on the host path when using -no-yazi variants.

```sh
nix profile add --refresh github:Yazelix/nova/stable#yazelix-no-helix
```

```sh
nix profile add --refresh github:Yazelix/nova/stable#yazelix-no-yazi
```

```sh
nix profile add --refresh github:Yazelix/nova/stable#yazelix-no-helix-no-yazi
```

```sh
nix profile add --refresh github:Yazelix/nova/stable#yazelix-no-rio
```

--------------------------------

### Install Yazelix Nova via Nix profiles

Source: https://github.com/yazelix/nova/blob/main/docs/installation.md

Commands to add stable, main, and edge versions of Yazelix Nova to the user profile with appropriate priorities.

```sh
nix profile add --refresh github:Yazelix/nova/stable
nix profile add --refresh github:Yazelix/nova/main#yazelix-main --priority 6
nix profile add --refresh github:Yazelix/nova/edge#yazelix-edge --priority 7
```

--------------------------------

### Update a Home Manager or nix-darwin installation

Source: https://github.com/yazelix/nova/blob/main/docs/installation.md

Run this command from the configuration directory that declares the Yazelix input. Follow up with the standard switch command for your configuration.

```sh
nix flake update yazelix
```

--------------------------------

### Run Yazelix Nova without installation

Source: https://github.com/yazelix/nova/blob/main/README.md

Execute the application directly using nix run to test the stable channel.

```sh
nix run github:Yazelix/nova/stable -- launch
nix run github:Yazelix/nova/stable -- enter
```

--------------------------------

### Managed Yazi Plugin Layout

Source: https://github.com/yazelix/nova/blob/main/docs/runtime-notes.md

Example directory structure for a managed Yazi plugin.

```text
~/.config/yazelix/yazi/plugins/foo.yazi/main.lua
~/.config/yazelix/yazi/flavors/foo.yazi/flavor.toml
~/.config/yazelix/yazi/init.lua
~/.config/yazelix/yazi/theme.toml
```

--------------------------------

### Import Nova module

Source: https://github.com/yazelix/nova/blob/main/docs/installation.md

Enable the Nova module within your Home Manager configuration.

```nix
{ inputs, ... }: {
  imports = [ inputs.yazelix.homeManagerModules.default ];
  programs.yazelix.enable = true;
}
```

--------------------------------

### Launch and Enter Development Environment

Source: https://github.com/yazelix/nova/blob/main/README.md

Use these Nix commands to launch or enter the Yazelix development environment from a local checkout.

```sh
nix run .#yazelix -- launch
nix run .#yazelix -- enter
```

--------------------------------

### Select Main package variant

Source: https://github.com/yazelix/nova/blob/main/docs/installation.md

Explicitly set the package to the main variant to retain the launcher.

```nix
programs.yazelix.package =
  inputs.yazelix.packages.${pkgs.system}.yazelix-main;
```

--------------------------------

### Configure Yazi-free package

Source: https://github.com/yazelix/nova/blob/main/docs/installation.md

Use the no-yazi variant while providing Yazi through Home Manager packages.

```nix
{
  home.packages = [ pkgs.yazi ];
  programs.yazelix.package =
    inputs.yazelix.packages.${pkgs.system}.yazelix-no-yazi;
}
```

--------------------------------

### Configure fully managed components

Source: https://github.com/yazelix/nova/blob/main/docs/installation.md

Use the no-helix-no-yazi variant with custom editor settings.

```nix
{
  home.packages = [ pkgs.neovim pkgs.yazi ];
  programs.yazelix = {
    package = inputs.yazelix.packages.${pkgs.system}.yazelix-no-helix-no-yazi;
    config.settings.editor.command = "nvim";
  };
}
```

--------------------------------

### Promote main to stable

Source: https://github.com/yazelix/nova/blob/main/docs/development.md

Commands to verify and push a specific revision from main to the stable branch.

```sh
git fetch origin main stable
git merge-base --is-ancestor origin/stable <sha>
git merge-base --is-ancestor <sha> origin/main
git push origin <sha>:stable
```

--------------------------------

### Configure Helix-free package

Source: https://github.com/yazelix/nova/blob/main/docs/installation.md

Use the no-helix variant and specify a custom editor command.

```nix
programs.yazelix = {
  package = inputs.yazelix.packages.${pkgs.system}.yazelix-no-helix;
  config.settings.editor.command = "nvim";
};
```

--------------------------------

### Define Nova configuration settings

Source: https://github.com/yazelix/nova/blob/main/docs/installation.md

Set appearance, shell, editor, and external configuration file sources.

```nix
programs.yazelix.config = {
  settings = {
    appearance.mode = "light";
    shell.program = "fish";
    editor.command = "nvim";
    welcome.enabled = false;
  };

  starship.text = ''
    [character]
    format = ":: "
  '';

  helix.languages.source = ./languages.toml;
  rio.source = ./rio.toml;
  yazi.config.source = ./yazi.toml;
  yazi.starship.source = ./yazi-starship.toml;
};
```

--------------------------------

### Automate Yazi Configuration Materialization

Source: https://github.com/yazelix/nova/blob/main/docs/runtime-notes.md

Use the yzx CLI to materialize an effective configuration directory for Yazi without launching the full runtime.

```sh
effective_config="$(
  yzx yazi-config materialize \
    --user-config-dir "$PWD/yazi" \
    --state-dir "$PWD/state"
)"
YAZI_CONFIG_HOME="$effective_config" yazi --debug
```

--------------------------------

### Create Named Sessions

Source: https://github.com/yazelix/nova/blob/main/README.md

Use the --session flag to initialize a fresh named session for your workspace.

```sh
yzx enter --session project
yzx launch --session project
```

--------------------------------

### Configure Yazi theme

Source: https://github.com/yazelix/nova/blob/main/docs/configuration.md

Sets the dark and light theme for Yazi using the Yazelix configuration.

```nix
programs.yazelix.config.yazi.theme.text = ''
  [flavor]
  dark = "catppuccin-mocha"
  light = "catppuccin-mocha"
'';
```

--------------------------------

### Default Configuration Root

Source: https://github.com/yazelix/nova/blob/main/docs/configuration.md

The standard directory path for Nova configuration files.

```text
~/.config/yazelix/
```

--------------------------------

### Run local checks and builds

Source: https://github.com/yazelix/nova/blob/main/docs/development.md

Commands to verify flake integrity and build specific project variants.

```sh
nix flake check
nix flake show --all-systems
nix build .#yazelix --no-link --print-build-logs
nix build .#yazelix-no-helix --no-link --print-build-logs
nix build .#yazelix-no-helix-no-yazi --no-link --print-build-logs
nix build .#checks.x86_64-linux.rio_contracts --no-link
nix build .#checks.x86_64-linux.host_yazi_contracts --no-link
nix build .#checks.x86_64-linux.no_helix_contracts --no-link
nix build .#checks.x86_64-linux.yzx_yazi_materialization --no-link
```

--------------------------------

### Override inputs for local development

Source: https://github.com/yazelix/nova/blob/main/docs/development.md

Nix commands to run the project using local sibling repositories for various dependencies.

```sh
nix run --override-input rio ../nova-rio
nix run --override-input yazelixZellij ../nova-zellij
nix run --override-input yazelixHelix ../nova-helix
nix run --override-input yazelixZellijPopup ../zellij-popup
nix run --override-input novaBar ../nova-bar
nix run --override-input yazelixZellijPaneOrchestrator ../zellij-pane-orchestrator
nix run --override-input yaziBistro ../yazi-bistro
```

--------------------------------

### Migrate from Yazelix Classic

Source: https://github.com/yazelix/nova/blob/main/README.md

Run the migration bridge using the v17.12 tag to translate existing configuration files.

```sh
nix run github:Yazelix/nova/v17.12#yazelix -- launch
```

--------------------------------

### Initialize Yazi Plugin

Source: https://github.com/yazelix/nova/blob/main/docs/runtime-notes.md

Lua code to initialize a plugin within the Yazi configuration.

```lua
require("foo"):setup()
```

--------------------------------

### Promote edge to main

Source: https://github.com/yazelix/nova/blob/main/docs/development.md

Commands to verify and push a specific revision from edge to the main branch.

```sh
git fetch origin edge main
git merge-base --is-ancestor origin/main <sha>
git merge-base --is-ancestor <sha> origin/edge
git push origin <sha>:main
```

--------------------------------

### Verify runtime flake changes

Source: https://github.com/yazelix/nova/blob/main/.agent-protocols.local.md

Standard commands to validate and build the project flake.

```sh
nix flake check
nix flake show --all-systems
nix build .#yazelix --no-link --print-build-logs
nix profile add --refresh /home/lucca/pjs/yazelix-dir/yazelix --profile <tmp>
```

--------------------------------

### Configure Starship Source in Nix

Source: https://github.com/yazelix/nova/blob/main/docs/configuration.md

Use this Nix configuration to define the Starship source for both the main program and the Yazi integration.

```nix
let
  prompt = ./starship.toml;
in {
  programs.yazelix.config = {
    starship.source = prompt;
    yazi.starship.source = prompt;
  };
}
```

--------------------------------

### Configuration Directory Structure

Source: https://github.com/yazelix/nova/blob/main/ARCHITECTURE.md

The directory layout for Yazelix configuration files, showing the hierarchy of packaged defaults and user-specific overrides.

```text
~/.config/yazelix/
  config.toml              # optional sparse semantic overrides
  rio/config.toml          # complete native Rio config; seeded once with themes/
  zellij/config.kdl        # guarded scalar sidecar
  zellij/plugins.kdl       # extra plugins only
  starship.toml            # optional sparse prompt overrides
  nu/{env,config}.nu       # after packaged Nu
  helix/*                  # lazy; created on tab use
  yazi/{yazi.toml,theme.toml,package.toml,starship.toml,init.lua,keymap.toml,plugins/,flavors/}
```

--------------------------------

### Configure Neovim to reveal buffer in Yazi

Source: https://github.com/yazelix/nova/blob/main/docs/configuration.md

Use this keybinding to reveal the current buffer in the Yazelix Yazi popup from Neovim.

```lua
vim.keymap.set("n", "<M-r>", function()
  local path = vim.api.nvim_buf_get_name(0)
  if path ~= "" then vim.fn.jobstart({ "yzx", "reveal", path }) end
end, { desc = "Reveal buffer in Yazelix Yazi popup" })
```

--------------------------------

### Link and apply custom Yazi flavor

Source: https://github.com/yazelix/nova/blob/main/docs/configuration.md

Links a custom flavor repository and configures Yazelix to use it.

```nix
programs.yazelix.config.yazi.theme.text = ''
  [flavor]
  dark = "my-flavor"
  light = "my-flavor"
'';

xdg.configFile."yazelix/yazi/flavors/my-flavor.yazi".source =
  inputs.my-yazi-flavor.outPath;
```

--------------------------------

### Bind Smart Enter plugin

Source: https://github.com/yazelix/nova/blob/main/docs/configuration.md

Configures the keybinding for the Smart Enter plugin in Yazi.

```toml
[[mgr.prepend_keymap]]
on = "l"
run = "plugin smart-enter"
```

--------------------------------

### Promote main revision to stable

Source: https://github.com/yazelix/nova/blob/main/AGENTS.md

Use this command to advance the stable branch after all release checks and verification steps are complete.

```sh
git push origin <sha>:stable
```

--------------------------------

### Nushell Configuration Paths

Source: https://github.com/yazelix/nova/blob/main/docs/runtime-notes.md

The paths for environment and configuration files generated by Yazelix for Nushell.

```text
~/.config/yazelix/nu/env.nu
~/.config/yazelix/nu/config.nu
```

--------------------------------

### Importing Native Shell History into Atuin

Source: https://github.com/yazelix/nova/blob/main/docs/configuration.md

Commands to migrate existing shell history into Atuin. Run only one matching import to avoid duplicating records.

```sh
# Nushell's default plaintext history
atuin import nu

# Only if you configured Nushell to use SQLite history
atuin import nu-hist-db

# Bash, Zsh, or Fish native history
atuin import bash
atuin import zsh
atuin import fish
```

--------------------------------

### Declare Nova input in flake

Source: https://github.com/yazelix/nova/blob/main/docs/installation.md

Add the stable Nova repository to your flake inputs.

```nix
inputs.yazelix = {
  url = "github:Yazelix/nova/stable";
  inputs.nixpkgs.follows = "nixpkgs";
};
```

--------------------------------

### Default Runtime State Directory

Source: https://github.com/yazelix/nova/blob/main/docs/configuration.md

The default location for generated runtime state, configurable via environment variables.

```text
${XDG_DATA_HOME:-$HOME/.local/share}/yazelix
```

--------------------------------

### Define the Nova runtime chain

Source: https://github.com/yazelix/nova/blob/main/.agent-protocols.local.md

Represents the current runtime dependency chain for the project.

```text
yzx -> Nova Rio -> Yazelix Zellij fork
```

--------------------------------

### Agent Provider Search Order

Source: https://github.com/yazelix/nova/blob/main/docs/runtime-notes.md

The default provider selection order checked in the system PATH during the first agent launch.

```text
codex resume
grok
opencode
pi
claude --resume
```

--------------------------------

### Attach to Existing Sessions

Source: https://github.com/yazelix/nova/blob/main/README.md

Use the attach command to reconnect to a live session, preserving its current state and layout.

```sh
yzx enter attach project
yzx launch attach project
```

--------------------------------

### Define Custom Popup

Source: https://github.com/yazelix/nova/blob/main/docs/configuration.md

Add a custom popup under the [popups.<id>] section, ensuring the command and arguments are separated and the title is unique.

```toml
[popups.btm]
command = "btm"
args = ["--basic"]
title = "btm_popup"
keybinding = "Alt Shift B"
keep_alive = true
```

--------------------------------

### Agent Provider Storage Path

Source: https://github.com/yazelix/nova/blob/main/docs/runtime-notes.md

The file path where the selected agent provider is stored for subsequent launches.

```text
${YAZELIX_STATE_DIR}/agent/provider
```

--------------------------------

### Configure Helix normal mode keybindings

Source: https://github.com/yazelix/nova/blob/main/docs/runtime-notes.md

Enforces the reveal command mapping for the Alt-r key combination in the generated Helix configuration.

```toml
[keys.normal]
A-r = ':sh yzx reveal "%{buffer_name}"'
```

--------------------------------

### Pin external Yazi flavor

Source: https://github.com/yazelix/nova/blob/main/docs/configuration.md

Adds a non-flake repository as an input for custom Yazi flavors.

```nix
inputs.my-yazi-flavor = {
  url = "github:owner/flavor-repository";
  flake = false;
};
```

--------------------------------

### Yzx-open log file path

Source: https://github.com/yazelix/nova/blob/main/docs/configuration.md

The location where yzx-open writes its bounded logs.

```text
${YAZELIX_STATE_DIR}/logs/yzx-open.log
```

--------------------------------

### Configure Emacs to reveal buffer in Yazi

Source: https://github.com/yazelix/nova/blob/main/docs/configuration.md

Bind this function to a key in Emacs to reveal the current file buffer in the Yazelix Yazi popup. This replaces the default M-r binding.

```elisp
(defun yazelix-reveal-buffer ()
  "Reveal the current buffer in the Yazelix Yazi popup."
  (interactive)
  (if buffer-file-name
      (start-process "yzx-reveal" nil "yzx" "reveal" buffer-file-name)
    (user-error "Current buffer does not visit a file")))

(global-set-key (kbd "M-r") #'yazelix-reveal-buffer)
```

--------------------------------

### Count tracked source lines

Source: https://github.com/yazelix/nova/blob/main/docs/development.md

Command to calculate the total lines of code in the project, excluding generated or binary files.

```sh
git ls-files | grep -Ev '^\.beads/|\.lock$|^assets/' | xargs wc -l
```

--------------------------------

### Define Yazi Flavor

Source: https://github.com/yazelix/nova/blob/main/docs/runtime-notes.md

TOML configuration for defining dark and light mode flavors.

```toml
[flavor]
dark = "foo"
light = "foo"
```

--------------------------------

### Promote revisions to git channels

Source: https://github.com/yazelix/nova/blob/main/.agent-protocols.local.md

Commands to advance the main and stable channels using specific commit SHAs.

```sh
git push origin <sha>:main
```

```sh
git push origin <sha>:stable
```

--------------------------------

### Define Helix configuration directory path

Source: https://github.com/yazelix/nova/blob/main/docs/runtime-notes.md

The directory path where managed user configuration files for Helix are stored.

```text
~/.config/yazelix/helix/
```

--------------------------------

### Restricted Zellij Configuration Keys

Source: https://github.com/yazelix/nova/blob/main/docs/runtime-notes.md

List of top-level nodes that are rejected if uncommented in the managed Zellij sidecar.

```text
keybinds
default_shell
default_layout
layout_dir
layout
plugins
load_plugins
support_kitty_keyboard_protocol
env
session_name
attach_to_session
```

--------------------------------

### Disable Keybinding

Source: https://github.com/yazelix/nova/blob/main/docs/configuration.md

Set a keybinding field to false to unmap the action without removing the underlying command or behavior.

```toml
[keybindings]
screen = false
```

--------------------------------

### Define the git ancestry invariant

Source: https://github.com/yazelix/nova/blob/main/.agent-protocols.local.md

Specifies the required linear history relationship between git channels.

```text
stable ⊆ main ⊆ edge
```
Tokens:
Raw