Issue #537: nikaia new, and a #! line so a .nika file runs as a script

Open and answer this issue on GitHub.

tools, ready · opened 2026-10-07 · updated 2026-10-09 · 1 comment

Records: Part III 13.1 (nikaia new my_project generates the structure), 13.2 and ADR-260 D4 (nikaia run f.nika, built in #132).

Where it stands. One file already runs on its own: nikaia run f.nika builds it as a project kept in the user’s cache, keyed on its path. What is missing is the two ends around it:

1. nikaia new is specified and not built. guide/getting-started.md says so (“There is no nikaia new yet, so create the two files by hand”), so the first thing a tester does is type a nikaia.toml from a page.

2. A file cannot be its own command. Nothing in the parser treats a leading #! line, so a small tool can’t be written as

   #!/usr/bin/env -S nikaia run
   fn main() {
       println("Hello, Nikaia!")
   }

   and started with ./hello.nika. This does not touch the no REPL decision: a file is still a whole program, and the analysis still sees all of it.

To decide

• What nikaia new writes: the manifest with user-parallelism spelled out (as the guide does) or the defaults only; a tests/ directory with one output test, since every example package has one; a .gitignore for target/; and whether it refuses a non-empty directory.
• The #! rule: only on line 1, only in a file that is an entry point, ignored as a whole line (its span still counted, so diagnostics keep their line numbers). Whether nikaia run accepts arguments after the file without -- when started this way, since the kernel passes the script’s arguments straight after the path.
• Whether the guide’s Getting started then opens with nikaia run hello.nika and moves projects to the second step.

Comments

keywan-ghadami, 2026-10-09

Decided (owner, 2026-10-09)

Checked (0.0.711):

Try	Result
nikaia new x	unrecognized subcommand 'new'
#!… on line 1	Didn't expect '#' here.
nikaia run s.nika a b	unexpected argument 'a' (arguments only after --)
nikaia run s.nika -- a b	runs with a b

The third row decided the second question. The kernel starts a script as nikaia run ./s.nika a b, without --, so a #! line alone would not be enough.

Where it is written: ADR-260 D6-D8 and Part III 13.1-13.2 (0.0.712).

• D6: everything after the file is the program’s, including -x, as go run does. A switch of nikaia run stands before the file, and -- still works.
• D7: a #! in the first two bytes of the file that holds main skips that line, which still counts for line numbers. Elsewhere # stays an error.
• D8: nikaia new name writes, and refuses a directory that exists and is not empty:
  • nikaia.toml with name and version only;
  • src/main.nika printing Hello, Nikaia!;
  • tests/main.stdout with that line;
  • .gitignore with target/.
• The guide opens with a single file (nikaia run hello.nika); projects come second.

To build

1. D6: arguments after the file go to the program. Tests:
   • nikaia run s.nika a -v b hands the program a -v b;
   • nikaia run --release s.nika x still reads --release as a switch;
   • nikaia run s.nika -- a still works.
2. D7: the parser skips a first line starting #!. Tests:
   • the script above runs as ./s.nika a b (execute bit, #!/usr/bin/env -S nikaia run);
   • an error on line 3 of a file with #! is reported on line 3;
   • #! in a file without main, or on line 2, is refused.
3. D8: nikaia new. Tests:
   • nikaia new hello && cd hello && nikaia run prints Hello, Nikaia!;
   • nikaia test passes in it;
   • nikaia new on a non-empty directory is refused and writes nothing.
4. guide/getting-started.md:
   • step 1 is a single file with nikaia run hello.nika;
   • step 2 is nikaia new, replacing “There is no nikaia new yet”;
   • a short section on #! scripts.

   No version change.

---

Generated by Claude Code

Back to Open Issues