This would also close #7008

Thank you for the review and the ideas.

--scope argument

I think having --scope values interpreted as Typst code is quite valuable. It allows simple and expressive usage such as:

typst eval x+y --scope x=2 --scope y=6
# 8

This also closely mirrors the familiar eval function inside Typst itself.

Against interpreting scope values as strings

If --scope values were interpreted as plain strings (which you can emulate using --scope 'x="2"'), the result would be:

# "26"

This means we would lose a lot of flexibility, especially when leveraging shell interpolation, e.g. --scope x=$(echo 1).

Additionally—and as you already mentioned—there would be almost no functional difference compared to --input, making --scope essentially redundant.

Even though I don’t currently have a practical use case for it, interpreting scope values as Typst code also enables injecting math contexts or markup content, allowing for things like:

typst eval x+y --scope 'x="2"' --scope y='$6$'
# {"func":"sequence","children":[{"func":"text","text":"2"},{"func":"equation","block":false,"body":{"func":"text","text":"6"}}]}

I have no idea why you would ever need this—but experience shows that users come up with all sorts of unanticipated (yet valid) uses.

Against dropping --scope entirely

Most of the points above apply here as well. Without --scope, we would lose a great deal of flexibility. With only --input, examples like the following become much harder to write:

typst eval 'if x == 0 { query(heading) } else { query(heading.where(level: x)) }' \
  --scope x=$(<some script yielding a level>) \
  --in ...
# headings of all levels or only specific levels

Without --scope, the same dynamic value would have to be interpolated multiple times or parsed manually from sys.input via JSON or similar. This adds complexity and reduces expressiveness.

--mode argument

From a practical standpoint, this argument can likely be omitted. Inside Typst itself it makes sense, since the evaluator actually renders math or content blocks. But from the CLI’s perspective, the output becomes something like:

{
  "func": "equation",
  "block": false,
  "body": {
    "func": "frac",
    "num": { ... },
    "denom": { ... }
  }
}

(example generated by the current implementation using
typst eval '#a/#b' --mode math --scope a='$2 times 3$' --scope b='6' --pretty)

This form is not particularly meaningful for most CLI use cases.

Alternative

If we remove the --mode argument and always evaluate in “code” mode, but a rare situation arises where a user actually does want the math-mode AST, they can simply wrap the expression:

typst eval '$#a/#b$' --scope a='$2 times 3$' --scope b='6' --pretty

This seems like a reasonable workaround, especially since such cases should be rare.

Downsides of having --mode

That said, keeping the argument incurs very little maintenance cost. The biggest issue is the ambiguity and conversion between args::SyntaxMode and syntax::SyntaxMode.

Depending on how significant you consider that friction, offering a --mode argument (defaulting to "code") could still be reasonable—especially since it mirrors the #eval(...) behavior from inside Typst, making the CLI more familiar for existing users.

TL;DR

--scope
+ Strong yes — significant flexibility, meaningful difference from --input, powerful shell integration.

--mode
~ Mild benefit, low maintenance cost — can reasonably go either way depending on project values and philosophy.

Thanks for the your detailed response. It's worth noting that the repetition could also be worked around like this:

typst eval "{ let x = $(echo 2); x + x + 2 }"

However, this easily makes for a code injection opportunity! I'm not sure what attack surface we're considering for typst eval yet. But having such an injection hazard is not great.

This is less bad with scope, but I think it's still somewhat problematic and could be a pitfall. Something like --scope x="$(cat user-input)" could be attacked with " + read("secret/file") + ". And even if you don't have an attacker, you'd have to deal with Typst's escape sequences in strings.

Of course, you can avoid this by using sys.inputs if you want a string. But the convenience of --scope will make it the first thing people reach for.

Considering that

• sys.inputs avoids such security problems by default
• you can still use eval(sys.inputs.x) explicitly within your code to emulate --scope

it might be a safer and better default. If you're expecting integers, I think it's also reasonable to be explicit about that and use int for parsing the inputs.

There is also the question of whether --scope would interact with --mode. (In the built-in eval function this is not relevant because the dictionary always contains values.)

Good point. I honestly did not think about potential attack surface on this one, but given your explanation, I agree that --input is enough and users can optin to risky input by using eval(sys.inputs.<whatever>).

The repition mitigation with { let x = eval(sys.inputs.x); x + x + 2 } works, but I feel like this is a lot of boilerplate for something we easily can have with the current design. Especially considering multiple --scope/--input arguments. I wonder if there could be a cleaner/less verbose/less boilerplaty way? 🤔

Summary

Given your arguments:

• I agree with removing --scope in favor of the safer --inputs alternative.
• Maybe there is a better way for defining variables in the scope of the evaluated statement?
  Your suggestion (let binding) seems to fit the Typst design philosophy perfectly though, so there may very well be no further room for improvement.
• I assume the --mode argument is off the table then?

There is also the question of whether --scope would interact with --mode. (In the built-in eval function, this is not relevant because the dictionary always contains values.)

I think (and that is how I implemented it for now) --mode should only affect the received expression. --scope is unaffected by this and always evaluated as code. The reason for this is behaviour parity with the Typst #eval() function, where values in the scope Dict are always interpreted as code (unless put into math using $...$ or content [...] mode, same as in CLI).

I'd say lets remove both --scope and --mode then. The downsides of --scope seem significant and after all it's always easier to add something later if we reconsider it than to remove it.

Done

Thanks a lot for the help along the way and the documentation/messages improvement from your side.

Thank you, great work!