Configuration reference

This page is the complete reference for how the CLI is configured. For a guided introduction, start with Authentication & API keys and Organizations, labels & categories.

Config file

The CLI stores its settings in a JSON file in your home directory:

~/.sayr/config.json

The file is created the first time something is saved (by login, config set-org, or config set-base-url), with owner-only permissions (0600) because it holds your token. A missing file is treated as empty. It looks like this:

{
	"token": "api_xxxxxxxx",
	"baseUrl": "https://api.sayr.io",
	"defaultOrg": "platform"
}

sayr logout rewrites the file as empty, which removes all three fields. Every field is optional.

Profiles

One config file holds one login. To keep more than one, for example production and a local dev backend, use a profile. A profile is a separate config file, ~/.sayr/config.<profile>.json, chosen with the SAYR_PROFILE environment variable:

SAYR_PROFILE=staging sayr login --token api_xxxxxxxx --base-url https://api.staging.example.com
SAYR_PROFILE=staging sayr task list --org platform

Profile names may contain only letters, digits, ., _, and -. Anything else is an error. An unset or empty SAYR_PROFILE means the default ~/.sayr/config.json.

sayr-local

The package ships a second command, sayr-local. It's the same CLI with SAYR_PROFILE=local forced on, so it reads and writes ~/.sayr/config.local.json. That's the easy way to keep a local sayr backend beside your normal production login:

sayr-local login --token api_xxxxxxxx --base-url http://localhost:5468
sayr-local task list --org platform

sayr and sayr-local never interact. sayr-local sets the profile even if SAYR_PROFILE is already set in your shell.

Environment variables

These are all the environment variables the CLI reads.

SAYR_NO_INTERACTIVE leaves guided mode on when it's unset, empty, or set to 0, false, no, or off (in any case, ignoring surrounding spaces). Any other value turns it off, and 1 is the one to use. It doesn't affect login's token prompt or the confirmation that releases publish and releases delete ask for. Those follow --token, --yes, --json, and whether there's a terminal.

There is no environment variable for the organization or the output format.

Precedence

When the same setting can come from more than one place, the first match wins:

The organization step applies to every command that takes --org, including read-only ones such as task list. When the organization comes from the picker, the CLI suggests sayr config set-org so you aren't asked again.

login is the one exception: it uses only its own --token and --base-url flags (or a prompt for the token, and the default URL), and never the environment or a previously stored token or URL. It does keep the stored defaultOrg.

Defaults

The CLI always calls <base URL>/api/public/v1/me/... with an Authorization: Bearer <token> header, and it trims trailing slashes from the base URL. Set the base URL to the API server's address only, such as http://localhost:5468, without a path.

The config commands

sayr config get
sayr config set-org platform
sayr config set-base-url http://localhost:5468

config get prints the path of the config file it read, the base URL a real request would use (so a SAYR_BASE_URL override shows up), the stored default organization or (none), and the stored token cut down to its first eight characters, or (not set):

Config file: /Users/you/.sayr/config.json
baseUrl:    https://api.sayr.io
defaultOrg: platform
token:      api_xxxx…

With --json it prints { "baseUrl", "defaultOrg", "hasToken" }. It never includes any part of the token. config get reports what's stored in the file, so it doesn't show a SAYR_TOKEN from the environment. set-org and set-base-url save exactly what you type and don't check it against the API.

Shared flags by command

--help works on every command, and -V / --version on the top-level sayr command.

The commands with no --org either don't work inside an organization (login, whoami, config, orgs list) or address a comment by its own id, which already belongs to one organization. --json also turns guided mode off for that command.

task create [title] and releases create [name] take their title or name as an optional argument, which lets a terminal ask for it. Their own --help shows <title> and <name> because scripts must pass one, and without a terminal (or with --json) a missing one fails with error: missing required argument. --category takes a category name or id, and --set on task label and --add / --remove on releases label take label names or ids. See Names instead of ids.

Error codes

Errors print as ✗ <message> on standard error, and the command exits with code 1. Add SAYR_DEBUG=1 to also print the code and HTTP status in parentheses.

Codes the CLI raises

A few errors have no code and print just the message, such as an invalid SAYR_PROFILE name or an invalid --visibility on labels create. Usage errors from the argument parser, such as a missing argument or an unknown command or option, print as error: ... instead.

Errors from the API

When Sayr's API refuses a request, the CLI prints the message the API sent. With SAYR_DEBUG set, the code in parentheses is the API's own short error name. The common ones:

Related

• Authentication & API keys
• Scripting & automation
• Guided mode