AGENTS.md

1# Command-Line Guidelines
2 
3**Last Updated:** June 16, 2026
4 
5## CLI Conventions
6 
7- Prefer shared helpers such as `DryRunFlag(...)` and `YesFlag()` when adding command flags.
8- Build CLI role help from the registered role map (never hand-maintained literals) so each edition lists exactly the roles it accepts: `commands.UserRoleUsageFor(<map>)` / `RoleStrings.CliUsageString()`, passing CE `acl.UserRoles` or an edition's own static `auth.UserRoles` (Portal's includes `cluster_admin`; editions reference their own map, not the runtime-reassigned `acl.UserRoles`, to dodge the init-order problem). For federatable or cluster-instance contexts (LDAP `--ldap-role`, OIDC group→role, cluster grants) use `acl.ClusterInstanceRolesCliUsageString()`, which lists the instance-login roles and excludes `cluster_admin`/`visitor`.
9- Prefer `--json` for automation. `photoprism show commands --json [--nested]` exposes the command tree; add `--all` for hidden entries.
10- Use `internal/commands/catalog` to inspect commands and flags without running the binary; when validating large JSON docs, marshal DTOs with `catalog.BuildFlat` or `catalog.BuildNode`.
11- Expect `show` commands to return arrays of snake_case rows, except `photoprism show config`, which returns `{ sections: [...] }`, and `config-options` or `config-yaml`, which flatten to a top-level array.
12 
13## CLI Tests
14 
15- `urfave/cli` calls `os.Exit(code)` when a command returns `cli.Exit(...)`. Wrap command tests with `RunWithTestContext(cmd, args)` so `cli.OsExiter` is overridden and `go test` keeps running.
16- If you only need the exit code, call `cmd.Action(ctx)` directly and assert `err.(cli.ExitCoder).ExitCode()`.
17- Set `PHOTOPRISM_CLI=noninteractive` and or pass `--yes` to avoid prompts in tests and CI.
18- Some commands defer `conf.Shutdown()` or emit signals that close the DB. Avoid invoking `start` or sending process signals in unit tests.
19- `internal/commands/start.go` waits on `process.Signal`; avoid `process.Shutdown()` and `process.Restart()` in unit tests.
20 
21## Download CLI Workbench
22 
23Code anchors:
24- CLI flags and examples: `internal/commands/download.go`
25- Core implementation: `internal/commands/download_impl.go`
26- yt-dlp helpers: `internal/photoprism/dl/*`
27- Importer entry point: `internal/photoprism/get/import.go`
28 
29Focused runs:
30- `go test ./internal/commands -run 'DownloadImpl|HelpFlags' -count=1`
31- `go test ./internal/photoprism/dl -run 'Options|Created|PostprocessorArgs' -count=1`
32 
33FFmpeg-less tests:
34- Set `c.Options().FFmpegBin = "/bin/false"` and `c.Settings().Index.Convert = false` when the test is not validating remux behavior.
35 
36Stubbing yt-dlp without network:
37- Use a small shell script that prints minimal JSON for `--dump-single-json` and creates a file when `--print` is requested.
38- Supported harness env vars: `YTDLP_ARGS_LOG`, `YTDLP_OUTPUT_FILE`, and `YTDLP_DUMMY_CONTENT`.
39 
40Remux and defaults:
41- Pipe mode always remuxes through PhotoPrism ffmpeg and embeds title, description, and created time.
42- File mode relies on yt-dlp output and passes `--postprocessor-args 'ffmpeg:-metadata creation_time=<RFC3339>'` so imports still get `Created`.
43- Default remux policy is `auto`; use `always` when you need the most complete metadata.
44- `photoprism dl` defaults to `--method pipe` and `--impersonate firefox`; pass `-i none` to disable impersonation.
45 
46