Command line (CLI)

CLI authentication

Browser sign-in with the device flow, or an API key in an environment variable.

Which method to use

Situation	Method
Your computer with a browser.	`posty auth:login`
Server, container, scheduled run, CI.	`POSTY_API_KEY` environment variable

Browser sign-in

posty auth:login

The command opens a browser, where you approve access with a code. The CLI then stores the credential on your machine, so you don't have to put it in your scripts, and it doesn't end up in your command history.

The approval page opens even if you aren't signed in

This is intentional. If you aren't signed in, you first see what you are approving, including the device and code. You sign in only after that. Nothing is approved unless you sign in.

API key via an environment variable

If there's no browser, put the API key in an environment variable. Create the key in Postemi under Automations → Developers. See the Developer settings page.

export POSTY_API_KEY=psty_your_key
posty integrations:list

Stored sign-in credentials take precedence over the environment variable.
Pass the key through a secrets manager. Don't put it in the script or commit it to version control.
For scheduled runs, it's also a good idea to set the POSTY_TIMEZONE variable so the dates are unambiguous.

Status and logout

posty auth:status   # which workspace this machine is linked to
posty auth:logout   # delete the stored credentials

auth:status doesn't just print the status. It also checks the credential with a real call. If that works, authentication is working. Any errors after that relate to the command itself.

Workspaces

posty workspaces:list        # what the credential reaches; "current" is the active one
posty workspaces:use <id>    # every following command acts on it
posty workspaces:current     # the one commands act on now
posty posts:list --workspace <id>   # one command in another workspace

A key can reach one workspace or several: tick “All my workspaces” on the approval page for the rest. Channel ids belong to a workspace, so the CLI has to know which one you mean. auth:login asks when the key spans several; the choice is stored with your login, and POSTY_WORKSPACE or --workspace override it. Without a choice the API refuses a multi-workspace key with 403 on every route except workspaces:list, so nothing is ever posted to a guessed workspace.

Your own backend

By default, the CLI connects to the posty.hu service. To connect to another instance, use the --auth-server flag or the POSTY_API_URL variable.

export POSTY_API_URL=https://your-instance.example/api
posty auth:login --auth-server https://your-instance.example/api

Is something missing from this page? Email [email protected] or use the form on the Help page.