Docs
View as markdown

relate feedback

The relate feedback and relate agent-feedback commands, which run has which, the 30-day grant, the flags, what a report may hold, and the exit codes.

cli

The relate CLI has two feedback commands, one for each kind of run, as of relate 1.0.2. relate feedback belongs to a run with agent mode CLI defaults for a detected agent harness on a non-terminal stdout, or forced on: at most 100 rows printed per statement, the cut reported, TOON in a pipe. Read more in the glossary off: it prints a prefilled issue form for the relate repository and opens it in the browser, and it manages the grant that lets agents report. relate agent-feedback belongs to a run with agent mode on: it sends one structured report, and only while a person's grant is live. Neither command sends anything on its own decision: a person submits the issue form, and a person makes the grant.

Synopsis

relate feedback [TEXT | enable | disable] [--category NAME] [--expected TEXT] [--observed TEXT]
relate agent-feedback [--category NAME] --expected TEXT --observed TEXT [--command PATH] [--error-code CODE] [--model MODEL] [--request-id UUID]
RunHasThe other word
Agent mode offrelate feedback, listed by relate --helprelate agent-feedback is an unknown command, exit code 2
Agent mode onrelate agent-feedback, listed by relate --helprelate feedback is an unknown command, exit code 2

Agent mode is on with --agent-mode, with RELATE_AGENT_MODE=1, or under a detected agent harness with stdout not a terminal. relate agent-context lists both words in every run. Both commands are compiled into every build of the binary.

relate feedback

FormDoesPrints on stdout
relate feedback <text>Builds a new-issue URL for github.com/relatedb/relate from the text and opens it in the default browser. The command makes no request; the issue exists only after the form is submitted in the browser.The URL
relate feedbackPrints the state of the grant, then the usage linefeedback enabled until <time> (<destination>), or feedback disabled (<reason>)
relate feedback enableRecords a grant: agents may send reports for 30 days. Requires a terminal.feedback enabled until <time>: agent reports go to <destination> for 30 days
relate feedback disableClears the grantfeedback disabled

A text of more than one line gives its first line as the issue title and the rest as the body. A text of one line is the body, and the title is its first 80 characters, cut back to a space. enable and disable are always actions: a report whose text is one of those words is passed with --observed.

FlagArgumentDefaultScopeSinceDescription
--categoryNAMEfrictionrelate feedback—Prefix the issue title with a category: friction, unclear_error, unexpected_behavior or missing_capability.
--expectedTEXT—relate feedback—Append what was expected to the issue body.
--observedTEXT—relate feedback—The issue text, spelled as a flag instead of the TEXT argument; giving both is a usage error.

A — under Since: the data does not record the release that added the flag.

--category prefixes the issue title as [<name>].

The <reason> of a disabled grant is one of:

ReasonMeaning
DO_NOT_TRACK, RELATE_TELEMETRY or config fileUsage metrics are off, and that layer decided it (the layers). No report is sent while they are off, grant or not
not enabledNo grant was ever recorded
declinedA person answered no when asked
authorization expiredThe 30 days ran out

The grant

A grant is a person's decision, so relate feedback enable runs only on a terminal. It names the destination the reports go to, then writes the grant to the feedback object of config.json in the config directory, the file relate telemetry writes. A grant lasts 30 days.

The CLI also asks for the grant itself, in one line on a terminal with yes as the default answer:

WhenHow often
The first relate feedback with no argument that finds no grant and no recorded answerOnce per install
relate skill install and relate upgrade, as of relate 1.1.0Once per 30 days, while no grant is live

An empty answer, y or yes records the grant. Any other answer records a decline. With usage metrics off, the CLI never asks.

relate agent-feedback

relate agent-feedback sends one report under the grant and never prompts. Without a live grant it refuses, with exit code The number a relate run returns to the shell; each nonzero value names a class of failure, such as 2 for usage, 5 for conflict, 6 for a rejected statement. Read more in the glossary 1 and not_enabled in the message. With a grant it prints one JSON document on stdout that states the outcome.

FlagArgumentDefaultScopeSinceDescription
--categoryNAMEfrictionrelate agent-feedback—friction, unclear_error, unexpected_behavior or missing_capability.
--expectedTEXTrequiredrelate agent-feedback—What was expected: not blank, at most 255 bytes; a longer value is rejected, never cut.
--observedTEXTrequiredrelate agent-feedback—What happened, under the same rules as --expected.
--commandPATH—relate agent-feedback—The CLI command the report is about; kept only when it names a visible command, else dropped and named in dropped_fields.
--error-codeCODE—relate agent-feedback—The error code: fatal_error, usage_error, conflict, validation_error or timeout; any other value is dropped and named in dropped_fields.
--modelMODEL—relate agent-feedback—The agent model label: lowercase, at most 40 characters, a provider prefix or an o<digit> family name; else dropped and named in dropped_fields.
--request-idUUIDgeneratedrelate agent-feedback—A lowercase UUIDv4 request id; an invalid value is a violation and a fresh id is used. The same id can be sent again after a failed or unknown outcome.

A — under Since: the data does not record the release that added the flag.

The outcome document holds these keys:

KeyHolds
outcomesent, skipped, rejected, failed or unknown
reasonWhy, in one word
request_id, report_idThe ids of the request and of the report
elapsed_msThe time the send took
violationsThe rules a rejected report broke
dropped_fieldsThe flags whose values were dropped
payloadWhat was sent; present only when outcome is sent
receipt_pathThe local receipts file

What a report may hold

--expected and --observed are free text, and the CLI checks them before anything is sent. A report that holds any of the following is rejected whole, and its text is not recorded:

  • A URL, an email address, a host name or an IP address.
  • A file path or the name of a data file.
  • A secret.
  • Cypher, or pasted output.

A link to these docs or to the relate repository by path (relatedb.ai/<path>, github.com/relatedb/relate/<path>), or to the Neo4j Cypher manual (neo4j.com/docs/), is allowed. Beside the flags' values, a sent report holds a schema version, the CLI version, the operating system and architecture, what invoked the run (agent, script or human) and the agent harness's label; the flags cannot set those. Every rejection and every send appends one line to feedback-receipts.jsonl in the config directory.

With usage metrics off, a report under a live grant is not sent: the outcome is skipped, with exit code 0. Privacy and telemetry lists the destination and every way to stop a report.

The hint line

As of relate 1.1.0, a run with agent mode on that fails prints one more line on stderr, once, after its error:

hint: agents can report Relate friction to its developers — draft it, ask the person, then run 'relate agent-feedback'

A run with agent mode off never prints it. The line is on stderr, so the error object on stdout is unchanged.

Errors and exit codes

CommandExit codeWhenMessage on stderr
Either0An issue URL was printed, a state was printed, a grant was recorded or cleared, or a report ended sent or skippedNone
feedback1enable without a terminalError: feedback enable: refusing a terminal is required: the grant is a person's decision, not a script's
agent-feedback1No live grantError: agent feedback is not enabled (not_enabled): the grant is a person's, made at a terminal with 'relate feedback enable' (30 days per grant), or answered at the install/upgrade ask
agent-feedback1A report ended rejected, failed or unknownNone; the outcome document on stdout says why
feedback2An unknown categoryError: '<name>' is not a category; use one of friction, unclear_error, unexpected_behavior, missing_capability
feedback2The text given twiceError: feedback takes the text either as its argument or with --observed, not both
agent-feedback2A required flag is missingError: agent-feedback requires --expected
feedback2The word in a run with agent mode onError: unknown command: feedback. this run's feedback surface is 'relate agent-feedback'; the grant is managed by a person at a terminal ('relate feedback enable')
agent-feedback2The word in a run with agent mode offError: unknown command: agent-feedback. the person's feedback surface is 'relate feedback'; the agent surface is 'relate agent-feedback', and the grant is managed by a person at a terminal ('relate feedback enable')

Examples

These examples run with DO_NOT_TRACK=1 set, in a fresh home directory, so no command here sends anything or opens a browser. With usage metrics off, the state names the layer that turned them off:

relate feedback
feedback disabled (DO_NOT_TRACK)
Usage: relate feedback [TEXT | enable | disable] [--category NAME] [--expected TEXT] [--observed TEXT]

enable refuses when stdin is not a terminal, and disable clears a grant whether or not one exists:

relate feedback enable < /dev/null
echo "exit=$?"
relate feedback disable
Error: feedback enable: refusing a terminal is required: the grant is a person's decision, not a script's
exit=1
feedback disabled

With agent mode on, the agent's command exists and refuses without a grant. The hint line follows the error:

RELATE_AGENT_MODE=1 relate agent-feedback --expected "the version" --observed "it printed help" --command info
echo "exit=$?"
Error: agent feedback is not enabled (not_enabled): the grant is a person's, made at a terminal with 'relate feedback enable' (30 days per grant), or answered at the install/upgrade ask
hint: agents can report Relate friction to its developers — draft it, ask the person, then run 'relate agent-feedback'
exit=1

Each run has one of the two words. The other is an unknown command that names the right one:

relate agent-feedback --expected "the version" --observed "it printed help"
echo "exit=$?"
Error: unknown command: agent-feedback. the person's feedback surface is 'relate feedback'; the agent surface is 'relate agent-feedback', and the grant is managed by a person at a terminal ('relate feedback enable')
exit=2

See also