CLI Reference

Pointy's user repository is a regular Nix flake. The command line gives you the same evaluated definitions and builds the web UI and backend use. It is not a reduced diagnostic view, but the real thing. The examples below assume the repository root as the working directory and use 42 as a representative numeric step or project identifier; replace it with the id you intend to inspect.

The CLI is particularly useful for telling a repository-evaluation problem from a web or backend-layer problem, because it addresses the flake outputs directly. For the declarations that produce these outputs, see Setting Up the User Repository. For the semantics of the option types serialized into step configuration, see the Type Reference.

Flake outputs

System-independent outputs (.#pointy.*)

Per-system outputs (.#pointy.*)

Building steps

Build a step from your current checkout

nix build .#pointy.steps.42

This realizes the same derivation addressed by the backend and creates ./result as a symlink to its output in the Nix store.

Build the same output from a pinned commit

nix build "git+file://$PWD?rev=<commit-hash>&allRefs=true#pointy.steps.42"

This form mirrors the backend's commit-pinned evaluation model more closely than a working-tree build: both the workflow definition and the flake inputs are resolved from the named repository revision.

Get a step's output path without building

nix eval --raw .#pointy.steps.42.outPath

The command returns the deterministic store path expected for step 42 without realizing it. That path exists in the local store only after a successful build, which is why computing an output path and proving that the output is present are separate operations.

Check whether that output already exists in the store

nix path-info "$(nix eval --raw .#pointy.steps.42.outPath)"

Inspecting configuration

Show all template schemas

nix eval --json .#pointy.stepConfig | jq .

The result is the JSON object keyed by template name that the frontend reads when choosing widgets and assembling forms; inspecting it is therefore a direct way to verify what a template actually exposes after Nix module evaluation.

Show all preset bundles

nix eval --json .#pointy.presets | jq .

Show all step definitions

nix eval --json .#pointy.stepDefs | jq .

Show one step definition

nix eval --json .#pointy.stepDefs.42

Show all project definitions

nix eval --json .#pointy.projects | jq .

Inspect a step's Pointy metadata

nix eval --json .#pointy.steps.42.meta.pointy

This shows the metadata exported through passthru.meta.pointy, including type, id, requirements, args, and any optional notices.

Inspect a step's resolved resource requirements

nix eval --json .#pointy.steps.42.meta.pointy.requirements

Returns the resolved { cpu; ram; ior; iow; } for step 42. When the step definition includes its own requirements, that value appears; otherwise the template-level requirements function result is shown.

Show the evaluated srcFiles path

nix eval --raw .#pointy.srcFiles

This is useful for seeing what build-time path the flake exposes. If you want to edit source files, use your repository checkout, not the /nix/store/... path returned by this command.

Try an autocomplete function

nix eval --json --apply 'f: f { query = "py"; limit = 10; }' .#pointy.autocomplete.<template>.<key>

Autocomplete functions may use additional string or enum fields as context. Pass those fields in the attrset when reproducing a UI request from the CLI.

Inspecting build behaviour and outputs

List files in a step's output

nix build .#pointy.steps.42 && ls ./result

Inspect the evaluated installPhase

nix eval --raw .#pointy.steps.42.config.mkDerivation.installPhase

The evaluated installPhase is often the most informative first stop when a template builds differently from what its source appears to imply. It includes the values produced by module composition. Helper scripts created elsewhere in the template may still be represented as Nix store paths rather than expanded inline. Read the output as the final build expression, not as a source-code reconstruction.

Show all project output paths

nix eval --json .#pointy.projectOutPaths | jq .

The result is a nested project-id → step-id → store-path map, with /invalid standing in for steps that cannot be evaluated. When a project has validation errors, inspect .#pointy.projects.<project-id>.validationErrors first: output paths are only meaningful for steps whose project membership and templates still evaluate coherently.

Day-to-day patterns

Once you're comfortable with the commands above, a few patterns make day-to-day work smoother:

• Use nix eval --json ... | jq . for readable interactive inspection.
• nix show-derivation .#pointy.steps.42 shows the full .drv for a step.
• The web UI's share links and read-only commit views are backed by the same commit-pinned flake state shown above.