Editing

EDITING (writes .px; -o defaults to editing the input in place)
  -o OUT always gets the whole file: with FILE:SEL, OUT is a copy of FILE with the selected
  frames edited and every other frame as it was, and a note says so.
  To get only some frames, extract them. An OUT in another directory gets its @palette
  lines re-pointed from there ('@palette ../pal.px' in -o art/x.px), so it imports the
  same palette file. Edits rewrite only what changed: other lines keep their spelling and
  the blank lines and comments above them, and new frames get the file's spacing between
  @frame blocks. An edit changing nothing (set to the same key, flip of a symmetric frame) prints
  "no change: FILE" and writes nothing; one that edits several frames names them.
  --dry-run (any edit) prints its diff and writes nothing. There's no undo: use git.
  Coordinates (x,y, --region, --at) need FILE:SEL on a file of several frames, saying which
  ('FILE:*': all).
  Limits: sections are written in a fixed order (palette, @variant, @anim/@still, frames,
  unknown @sections), so an @anim written between frames moves up; a comment inside the
  file stays with the line below it and goes when that line goes (a removed frame, cut rows).
  flip FILE [-o OUT] [--v]          mirror selected frames left-right (--v: top-bottom)
      'flip hero.px:walk/left -o hero.px:walk/right' flips a copy (--replace: over its frames).
  shift FILE [-o OUT] --dx N --dy N [--region x,y,w,h] [--wrap] [--fill KEY]
      Move the frame's pixels (or only the region's) by dx,dy. Pixels moved past the frame's
      edge are dropped, and the pixels the move leaves behind (vacated) become '.', or KEY
      with --fill KEY (a floor under a moved prop). With --region the moved block may land
      outside the region; its '.' pixels don't overwrite what they land on.
      --wrap scrolls pixels around the edges (for animating tiles) instead of dropping them.
  set FILE[:frame] KEY x,y [x,y ...] [-o OUT]    paint single pixels ('.' erases)
      Prints "painted N px" ("erased" for '.').
  fill FILE[:frame] KEY [--region x,y,w,h] [-o OUT]   paint a rectangle (default: the frame; '.' clears)
  new OUT[:frame] --size WxH [--key K] [--palette P.px] [--still]
  new OUT --empty [--palette P.px]
      A blank frame ('.'), or one filled with K, in a new file or added to an existing one
      (placed like compose). --palette P.px starts a new OUT that imports P. A frame that
      already exists is E_DUP_FRAME: fill it instead. --still marks its group '@still GROUP'
      (new ui.px:icons/life --still).
      --empty starts a new OUT with no frames: the version line and, with --palette, its
      @palette line. It is where frames --copy-to puts another file's frames against a
      shared palette: 'new party.px --empty --palette palette.px', then 'frames
      keeper.px:walk --copy-to party.px --rekey'.
  put FILE[:frame] [-o OUT] < grid.txt
      Replace one frame's grid with the rows on stdin. Stdin is rows, or palette lines then
      rows; the keys the rows use join FILE's palette the way compose's layers do (a key
      FILE has in another color is E_KEY_CONFLICT), and other keys must be FILE's. Rows are
      checked like a file's (widths, keys), errors point at stdin's lines, and
      nothing is written on an error. Only that frame's lines change.
      A frame that doesn't exist yet is added, placed like new; a new FILE is started.
      Stdin has no variants: a key in FILE's color is FILE's key, variant colors and all, and
      a new key stays at its base color in FILE's variants.
  mask FILE[:frame] --keep x,y,w,h | --keep-circle cx,cy,r ... [--dither N] [--invert]
       [--keep-keys K,K | --drop-keys K,K] [-o OUT]
      Erase (set to '.') every pixel outside the rectangle or circle (kept: distance from
      the pixel to cx,cy <= r). --dither N fades the circle's last N px inside its edge
      with a 4x4 ordered (Bayer) dither: a light radius. --invert erases the inside and
      keeps the outside, dither band mirrored, so a mask and its --invert split the image
      with no overlap or gap. --keep and --keep-circle repeat, and mix: the kept area is
      their union, and --dither and --invert work over the union.
      FILE may be a PNG (a scene rendered at --scale 1: coordinates are its pixels): outside
      pixels become transparent. -o must be a .png too.
      --keep-keys W,T,t (or WTt) erases every pixel whose key isn't one of those; --drop-keys
      erases those keys' pixels. Alone, they mask by key over the whole frame; with shapes, a
      pixel stays only when both keep it (the shapes, --invert and --dither as above). .px only.
  crop FILE:frame x,y,w,h -o OUT[:frame] [--rekey [KEYS]] [--used-keys-only]
       [--variant-map NAME=V1,V2]
      Cut the w x h rectangle at x,y out of one frame into a frame of its own: 'crop
      hero.px:idle/0 4,0,8,8 -o parts.px:head'. The pixels left outside get no note (they're
      what crop is for); a rectangle that runs past the frame's edge (or starts at a
      negative x,y) gets '.' there. FILE:frame must be one .px frame.
      OUT is written as compose writes it, FILE's frame its one layer (see compose): a new
      OUT gets FILE's whole palette (--used-keys-only: the cut's keys), OUT:frame adds or
      replaces that frame in an existing OUT, and a plain OUT with one unnamed grid has it
      replaced. A key OUT has in another color is E_KEY_CONFLICT, with free keys; --rekey
      gives the cut those keys in OUT and leaves FILE as it is.
  extract FILE:SEL -o OUT [--inline-palette] [--replace]
      Write only the selected frames to a new OUT, with FILE's palette, @palette imports,
      variants, and @anim/@still lines (minus those of groups left behind;
      @anim lines in the order of the frames' groups): 'extract hero.px:walk/down -o
      walk.px'. An OUT that exists is E_FILE, since its frames would be lost (E_DUP_FRAME
      when it has one of the ids): 'frames FILE:SEL --copy-to OUT' adds them to it, and
      --replace overwrites it. --inline-palette makes OUT self-contained for a hand-off: the
      imported keys it uses become key lines, with their variant colors, and the @palette
      lines go. OUT renders exactly like the source frames, in every variant.
  recolor FILE a=b ['a<>b'] ['a>b'] [c=#rrggbb] [-o OUT] [--region x,y,w,h] [--variant V]
      a=b repaints key a's pixels as key b (optionally only inside --region); 'a<>b' swaps
      keys a and b (in the region) in one step; quote it: unquoted < and > are shell
      redirections. 'a>b' gives a's pixels a new key b, in a's color (and a's variant
      colors): when no pixel keeps a and a is FILE's own key, a's palette lines become b's
      (a rename), else b is added and a stays: it frees a key without a visible change;
      onto a key b already in a's color (a near-duplicate), the error says to write a=b, a repaint that
      looks the same. c=#hex changes key c's color everywhere. '.' works as a source key.
      Order: the key moves of one call apply together, each pixel by the key it had before
      the call, so no move feeds another: 'a<>b' c=a turns a's pixels to b and b's and c's
      to a, and a=b b=a is a swap too. The renames apply together as well: a key another
      'a>b' of the call renames away is free for a new key, so 'g>r' 'd>g' renames g to r and
      d to g, and 'a>b' 'b>a' swaps two keys' names (every pixel keeps its look). A key the
      call keeps (pixels outside --region or the selection draw with it, it is imported, or
      c=g paints with it) isn't free. A key moved twice is E_BAD_ARG. Color changes (V's:
      --variant V) set the palette, moving no pixels: c=#hex, c=d and 'b>t' t=#hex share a
      call.
  paste SRC[+h|+v|+hv] --into DST[:frame] --at x,y [--region x,y,w,h] [--under] [--rekey [KEYS]]
        [--variant-map NAME=V1,V2] [--align shift|pivot|bottom|bbox] [-o OUT]
      Copy SRC's frame (or --region of it) onto DST at x,y; '.' never overwrites. +h / +v
      mirror SRC first, as for compose layers and scene items (--region is then in the
      mirrored frame's coordinates). --under fills only DST's empty pixels: SRC goes behind.
      SRC's keys join DST as a compose layer's join an existing OUT: E_KEY_CONFLICT, the
      variant WARNINGs, --rekey [KEYS] and --variant-map work alike. --align: one paste
      follows a bob across frames.
  compose -o OUT[:frame] [--size WxH] [--under] [--rekey [KEYS]] [--used-keys-only]
          [--variant-map NAME=V1,V2] [--replace] [--dry-run] LAYER@x,y ...
  compose --map MAP [--tile N] -o OUT[:frame] [the options above] [LAYER@x,y ...]
      Stack single frames (later layers on top; '.' never overwrites) into one frame.
      Rules ('pxart help compose-rules' prints only these):
        - A new OUT gets the layers' whole palettes, drawn with or not (for shade ramps). When
          every layer imports the same @palette file, OUT imports it too; else its keys become
          key lines.
        - An existing OUT keeps its own palette, @palette and variants; each layer's keys join
          it.
        - Variants merge by name: OUT's night colors each layer's pixels as that layer's own
          file's night does, and a layer whose file has no night stays at its base colors in
          it. --variant-map dusk=night reads another name as OUT's dusk.
        - A key a layer has in another color than OUT's is E_KEY_CONFLICT; --rekey gives it a
          free key in OUT. The layers' files are read, never written.
        - OUT:frame adds that frame to OUT, or replaces it; a plain OUT is one unnamed grid.
      Examples: 'compose -o room.px tiles.px:cobble@0,0 hero.px:idle/0@4,2', 'compose -o
      party.px:keeper/walk keeper.px:walk/0@0,0 --rekey' (keeper.px's k is another color in
      party.px: it gets a free key there). --dry-run prints what compose says (notes,
      conflicts, --rekey's moves) and OUT's diff (a new OUT: every line); nothing is written.

      A new OUT (rule 1; a shared import re-pointed from OUT's directory): local keys follow
      the import, the keys the layers use first: a key layers have in different colors gets
      the color of the layer that uses it, else the earlier layer's, and one line per source
      file names its colors left out and why: a key none of the file's layers here
      draw with is no conflict, and OUT has the color of the layer named (which draws with it,
      or is the earlier layer). That line is a WARNING when the file needs a key it lost (its
      other frames draw with it, named, or a variant lists it unchanged or keeps it while
      recoloring most keys: a lamp kept lit); --rekey then keeps such keys under free keys in
      OUT.

      --used-keys-only gives a new OUT only the keys its frame uses (and their variant colors;
      a @palette they all import is still imported, since it adds no key lines), so check has
      no 'unused keys' to note. Not the default: the unused keys are often a material's
      ramp: a cloak drawn in its base key c still needs X x C w for 'shade --ramp XxcCw' to
      re-shade it. An existing OUT only ever gets the used keys. So they're no
      surprise, a new OUT's note names the keys its frame doesn't draw with, by file ('...
      from its layers' whole palettes (for shade ramps and recolors): wick.px's E'), and
      check's 'unused keys' note offers the palette --remove that drops them.

      An existing OUT (rule 2): a layer's key is added unless OUT has it in that color, in
      the colors the layer's file gives it in OUT's variants of the same name (a variant the
      file hasn't got leaves the key at its base color there, and a file with variants, none
      of them OUT's, gets a note saying so and naming the --variant-map that would read one
      as OUT's). A plain OUT that exists (no :frame) keeps its palette too, keys from an
      earlier run included, and a note says so: 'note: glade.px exists: keeping its palette
      (61 keys, @variant dusk); --replace starts it fresh' (as does an E_KEY_CONFLICT).
      --replace starts it as if new: the layers' palettes, nothing of the old file (not with
      OUT:frame, whose other frames it would drop, or with --under).

      Key conflicts: a key a layer uses in another color than OUT's (or an earlier layer's) is
      E_KEY_CONFLICT, one line per source file (all its layers: 'layers 1-4, 7 (field.px)')
      naming every key and both colors, and free keys for them ('s>a' 't>b'). The free keys
      are chosen once for the whole compose, so no two lines' suggestions collide: a key OUT
      already has in that color first, then the key an earlier file of this compose was given
      for a color that looks the same in every variant (two packs' one outline share one key,
      and the note says so), then letters and digits, then % + - / : ^ _, and only when those
      run out the keys a shell reads (! $ ` ' * ? [ ] { } ~ & ; | < > ( )) or pxart does (,
      and =). A key any layer's file has isn't free, used here or not. Two ways to use them:
        --rekey: compose gives those keys the free ones in OUT as it goes, and a note says
          which: 'note: --rekey gives field.px's keys free ones in scene.px: 's>a' 't>b'
          (field.px is unchanged)'.
        a copy: 'pxart recolor field.px 's>a' 't>b' -o rekeyed/field.px' (rekeyed/ beside
          OUT), then compose from rekeyed/field.px; the line prints it ready to run.

      --rekey KEYS touches only the keys it lists. --rekey o,r gives o and r free keys and
      leaves the others as they are (a key of another color is still E_KEY_CONFLICT, a variant
      clash still a WARNING). KEY=OUTKEY puts KEY on OUT's key OUTKEY instead of a free one:
      --rekey k=j,n=q uses OUT's j and q, which must be in k's and n's base colors (else
      E_KEY_CONFLICT), and must not be keys of the layer's file; where OUT's variants color
      them otherwise, a WARNING per key names each color that changes. Both mix: k=j,n,s gives
      n and s free keys, and r=r keeps r as it is on purpose. An entry FILE.px:KEY[=OUTKEY] is
      for that source file alone: --rekey o,girl.px:T=V puts girl.px's T on V, gives every
      file's o a free key, and leaves the other files' T alone (a file's own entry wins over
      one for every file; FILE.px is a path, or the name of one source file). When --rekey
      gives a key a free one though an existing OUT has its base color under another key (in
      other variant colors, so it wasn't reused), a note names that key and the --rekey list
      that uses it anyway: 'note: party.px has the base colors of k n as j q, in other variant
      colors; --rekey k=j,n=q uses those anyway'. After crop's --rekey, four digits are the
      rectangle; write --rekey=1,2,3,4 to name four digit keys there.

      The report: compose reports per source file, in layer order, one line per reason: what
      --rekey moved and why (another color there; OUT's base color but other variant colors; a
      key its layers here don't draw with that the file needs; a key --rekey KEY=OUTKEY
      named), the colors a new OUT left out, which of the file's frames draw with a key it
      lost, and one WARNING per key OUT's variants color otherwise ('WARNING: layer 2
      (keeper.px:idle) draws 'r' #c4473a in party.px's variant colors, not keeper.px's: dusk
      #a33a4c (keeper.px: #83344e); compose --rekey r gives it a key of its own'). An
      E_KEY_CONFLICT line offers the same moves --rekey makes, with the same reasons.

      Variants (rule 3) come along for the keys OUT has, in the colors of the layer whose
      key OUT has. Layers from files with different variants (a market's dusk, a keeper's
      night, a candle's dark): each of OUT's variants covers only the layers whose file has
      it, and a note per variant says which layers stay at their base colors in it.
      --variant-map dusk=night,dark (repeatable) builds OUT's dusk from each layer's first
      of dusk, night, dark, so every layer dims together; a new OUT's palette is then
      inlined (its variants are built, not imported). The map adds to the same-name lookup,
      never replaces it: it says only where OUT's dusk comes from, and OUT's other variants,
      night among them, still read each file's variant of the same name (a keeper's night is
      then OUT's dusk and OUT's night too), and may feed several maps. A new OUT merges a variant into the map's only
      when every file that has it gave it to the map (the keeper's night, read as dusk):
      then it gets no variant of its own. One that a file keeps as its own (its file has a
      dusk too) stays one of OUT's variants. With an existing OUT, whose variants stay its
      own, the map says which of each layer's variants to read as OUT's dusk (dusk must be
      one of OUT's). A key a layer draws in OUT's base color but that its file's variants
      color otherwise (one red awning, recolored by one pack's dusk and another's night), in
      a new OUT or an existing one, gets a WARNING: OUT's variants color those pixels OUT's
      way. --rekey gives such a key a free key of its own, as it does a key of another
      color, reusing a key of OUT only when it looks the same in every variant. crop writes
      a new OUT the same way, and crop, paste and frames --copy-to bring keys in the same
      way.

      Comments: the comments above the layers' key and @variant lines come along, as for
      palette --extract-to; a comment naming a key --rekey renamed says so: '# lamp colors
      (l, g) stay lit (renamed l>I g>J)'. The keys right below a key's comment in its file
      (the keys it is about: '# light-emitting keys' above f a i) stay below it. From
      several files, each saying which file's it is ('from keeper.px's @variant night, dusk
      here'), and one that names a variant --variant-map merged into another says so ('from
      player.px, whose dark is dusk here'). A @variant's comment names only the files whose
      variant lines gave OUT's own @variant keys, and when OUT imports the rest, says so
      ('from visitors.px's @variant night; the rest from pal.px's night'). An OUT whose
      palette is inlined also gets the palette files' header comments at the top of its
      palette, each with the files it came from.
      A new OUT's header says how it was made: '# composed by: pxart compose --map room.map -o
      room.px', its paths from OUT's folder (composing OUT whole again updates it). A variant
      WARNING about OUT then also offers composing it again, with --replace, once the sources
      have that variant.

      Frames and canvas: layers can be frames of one parts file: parts.px:hat@3,0
      parts.px:body@0,8. OUT:frame keeps OUT's other frames (OUT may be a palette-only file),
      and the 'wrote' line says when it replaced one. A new frame goes after the last frame of
      its animation (like dup), or at the end for a new animation. Canvas size: --size,
      else --map's, else the frame being replaced, else the other frames of its animation,
      else the first layer. Pixels outside the canvas are cropped; a note counts them.
      --under keeps OUT's frame and draws the layers behind it: they fill only its empty
      pixels (a floor or a shadow under a finished sprite). The frame must exist.

      From a map: --map MAP reads scene's tilemap (legend, rows, '---' layers, +b, a '#'
      legend line; see scene) and makes each cell a layer, drawn where scene draws it, then
      the LAYER@x,y given over them; --tile is scene's (N means NxN). Palette, --rekey and
      --variant-map work as for any layers. A legend entry with its own %VARIANT comes in
      that variant's colors, as a file of its own (tiles.px%dark; --rekey tells it from
      tiles.px), and a PNG in keys of its own: OUT's variants leave both as they are, as
      scene --variant does. So 'compose --map market.map -o market.px' renders as 'scene
      --map market.map --bg transparent --scale 1 -o market.png' does, pixel for pixel, in
      every variant too, except where a translucent pixel lands on another: a .px pixel is
      one key, so it replaces what scene blends.
  dup FILE:ID NEWID [--after ID | --replace] [-o OUT]
  dup FILE:GROUP NEWGROUP [--after ID] [--replace] [-o OUT]
      Copy a frame under a new id, placed after the last frame of NEWID's animation, or
      when that animation is new, after the source's whole animation (or after --after).
      A new animation inherits the source's @anim timing.
      A GROUP copies its frames (walk/0 -> run/0), @anim and @still lines too.
  anim-set FILE:GROUP [ms=N] [direction=D] [repeat=N] [pivot=X,Y] [--still | --no-still] [-o OUT]
      Write timing: updates the '@anim GROUP' line, or adds one, in the order of the frames.
      FILE:GROUP/ID (one frame) takes only ms=N and pivot=X,Y and sets that frame's own
      ('@frame ID ms=N pivot=X,Y'), which wins over the group's. KEY= with no value clears
      a setting.
      A path that is both a group and a frame means the group. Only that one line changes.
      --still adds '@still GROUP' (the group is no animation: UI icons, parts), --no-still
      removes it; FILE with no :GROUP (or FILE:*) --still writes '@still *' (every frame),
      unless every frame already is in a @still group: then it says so and adds nothing. An
      @anim line stays, unused while the group is still.
  palette FILE [--add k=#hex ...] [--variant NAME [--add k=#hex ...] [--keep KEYS]]
          [--variant NAME --derive-from base|VARIANT [--match FILE%V] [--darken F] [--tint COLOR]
           [--keep-lit KEYS] [--lift-darks]]
          [--comment KEY|@variant NAME 'text' [KEY 'text' ...]] [--comment-header 'text']
          [--hoist KEYS] [--export out.gpl|out.hex [--used]] [--extract-to P.px [--repoint]]
          [--remove KEYS [--to KEY]] [--in DIR] [--import P.px] [--order KEYS] [-o OUT] [--dry-run]
      Rules ('pxart help palette-rules' prints only these):
        - No flags lists the palette: each key, its color, where it comes from and how often
          it's drawn, then what each variant recolors.
        - Edits write FILE's own lines (-o OUT: a copy; --dry-run: a diff, nothing written). An
          imported key or variant is edited in its palette file: --hoist moves FILE's keys
          there, and --remove of an imported key takes it out there when no other sprite under
          the directory uses it.
        - A variant is key lines over the base: --variant NAME --add sets keys in it (a key in
          its base color stays lit), --keep lets keys inherit, and --derive-from builds a
          whole variant from the base (--match fits another palette's mood; keys darker than a
          quarter are held dark).
        - Only a variant's edits (--variant with --add, --keep or --derive-from) and --remove
          --to change how FILE renders. --add of base keys, --import, --hoist, --extract-to
          --repoint, --order, --comment and --remove of undrawn keys keep every pixel, in
          every variant.
        - Sharing one palette file: --extract-to P.px [--repoint] writes it from FILE,
          --import P.px points FILE at one, and --in DIR says which sprites under DIR import
          it.
      Examples: 'palette party.px' lists it; 'palette pal.px --variant night --add k=#120e22
      w=#9fb0d4'; 'palette pal.px --variant dusk --derive-from base --match mossback.px%dusk'.

      Listing: after the keys (rule 1), each variant's line: 'dusk: recolors (darker) o x X
      c C; inherits: e E q' (the keys it recolors, then the base keys it leaves alone, both
      in palette order). A recolor is darker, brighter ('brightens y W': lamps lit brighter
      at night) or as bright (Rec. 709 luma, times alpha). A key the variant lists in its
      base color (a lamp that stays lit at night) is neither: 'night: recolors (darker) k w;
      relists unchanged: l g; inherits: nothing'. The palette's comments come along: the
      palette files' header on top, a key's comment after its line ('E #ffe07a local #
      light-emitting keys'), each variant's comment under its line, and the comments on its
      key lines as 'y: # lit in rain: harbor lamp'. A palette file has no 'used' column; --in
      DIR counts the .px files under DIR that import it ('imported by 3 of the .px files under
      crossover/') and, per key, how many of them draw with it ('used by 2 files').

      Base keys: --add k=#hex (or a palette line as the file has it, 'k #hex') adds them.

      Authoring a variant: with --variant NAME, --add sets the keys in that variant instead,
      over what it had, and makes the variant when FILE has none by that name (the example
      above). --variant NAME --keep l,g lets keys inherit the
      base colors: their lines in the variant go, and a key an imported variant recolors gets
      its base color on a line of FILE's own, since the import can't change from here. --add
      and --keep can share one call; the keys must be in the base palette. A key --add gives
      the color it already has is left, and said so: 'k is already #0f0f22 in night;
      unchanged'.

      Deriving a variant: --variant night --derive-from base --darken 0.35 --tint '#10183060'
      --keep-lit y,W sets every key of FILE's palette (imported ones too, unless FILE imports
      a night) in night from its base color (or from another variant's: --derive-from
      dusk), each channel times 1 - F (--darken 0.35 keeps 65%), then the --tint color laid
      over at its alpha, the math of scene --tint; the --keep-lit keys keep their
      --derive-from color, listed as lamps kept lit. A key that comes out in its base color
      gets no line. --add in the same call then sets single keys over the derived ones.

      --match FILE%dusk (or FILE:dusk; FILE alone means the variant being made) first maps
      each channel the way FILE's own base -> dusk does, a gain and an offset per channel
      fitted by least squares over the keys that variant recolors (not the ones it relists,
      the lamps), then --darken and --tint as above: the example above gives the cast
      another pack's dusk (a red gain, a blue offset), where one darken and one tint move
      every channel alike. The output prints the fit: 'r x0.92 -17, g x0.81 -11, b x0.78
      +10'. The hold: a key darker than a quarter (Rec. 709 luma, .2126 R + .7152 G + .0722
      B of the sRGB values, under 64) never comes out with a higher luma than its
      --derive-from color: it is scaled back to that luma, its hue kept (a warmer red may
      look a shade lighter), and listed as held, so a near-black outline stays dark under a
      blue tint or offset; else 'held: none'.
      --lift-darks lets the derive brighten them (a fog), and names the ones it did; --add
      sets one anyway.

      Comments: --comment KEY 'text' sets the comment right above FILE's line for KEY
      (replacing the comment lines there; blank lines stay); --comment @variant night 'text'
      the one above '@variant night', which --extract-to and compose carry as the variant's
      section note; with --variant NAME, --comment KEY is KEY's line in that variant. A line
      of FILE's own: an imported key or variant is commented in its palette file.
      --comment-header 'text' sets the comment at the top of FILE. '' removes a comment; a
      newline in the text makes two comment lines. One --comment takes several in turn
      ('palette pal.px --comment y "lamp" E "flame"'), and both repeat and go with --add in
      one call (the key added first): 'palette pal.px --variant night --add k=#120e22
      --comment @variant night "night: only lamps glow"'.

      Removing keys: --remove k,n takes FILE's own keys out: their key lines, their lines in
      FILE's variants, and the comments above those. A key a frame still draws with is
      E_SELECT (naming the frames and how many px), unless --to j repaints those pixels as j
      first: 'palette party.px --remove k,n --to j'. An imported key is repainted the same way
      in FILE, then removed from the palette file that defines it only when no other .px under
      DIR uses it (draws with it, or lists it in a variant, with no key line of its own); DIR
      is --in DIR, else the directory holding both FILE and the palette file. Otherwise it
      stays there, and a line names who uses it: 'b stays in pal.px: cavegirl.px uses it'.
      A palette file's own --remove can't see the sprites that import it: check them after
      (palette pal.px --in DIR shows who draws with each key).

      Order: --order o,t,k (or otk) moves FILE's own key lines to the top of its palette in
      that order, each with the comment and blank lines above it, the other keys after them as
      they were: group a material's ramp, or put the outline first. Variants and a
      '. transparent' line keep their places.

      Sharing a palette file: --import P.px adds '@palette P.px' to FILE (re-pointed from
      FILE's directory) and drops FILE's key lines P has in the same colors (and their variant
      lines P's variants say already), saying which: 'dropped o t k (their key lines: the same
      colors in pal.px)'. A key FILE has in another color than P's is E_KEY_CONFLICT, with
      free keys for FILE's and the recolor that moves them ('pxart recolor boy.px 'k>a''),
      then --import again. FILE renders as before, in every variant it had: where P's variant
      of that name would recolor a key FILE keeps, FILE's variant lists the key's color, and
      says so. A variant only P has comes along (a note says so).

      --hoist l,g moves FILE's own keys into the palette file it imports (its one @palette),
      with their lines in FILE's variants and the comments above both, so every sprite that
      imports it gets them; FILE renders as before. A key the palette file has in another
      color is E_KEY_CONFLICT (give FILE's a free key first: recolor FILE 'l>L'); a variant
      line the palette file has in another color stays in FILE.

      --extract-to P.px writes FILE's whole palette as a palette file for @palette: every key
      FILE renders with (imported ones too, local ones winning) and every variant, with the
      comments that document them: those above key and @variant lines (a section comment, '#
      glow: left out of dusk on purpose'), from FILE and the palette files it imports, and a
      palette file's header comment (a sprite's header is about the sprite and stays).
      --repoint then replaces FILE's @palette, key and @variant lines with '@palette P.px'
      (re-pointed from FILE's directory): FILE renders the same, and other sprites can share
      P.px.