Authentication and configuration

The CLI signs in with a personal key and saves your settings in profiles. Each profile stores a Mixpost address, a key and a default workspace. You can create one profile per instance, for example one for production and one for staging, and switch between them.

Log in

Create a personal key first: open the user menu, click API, then Create a personal key. See Create a personal key.

Then save it in a profile:

mixpost auth login

On a terminal, auth login shows a link to the page where you create keys, then asks for the key. The key is not shown as you type. If the profile already has a key, press Enter to keep it. You can run auth login again at any time to replace an expired key.

Before saving, the CLI makes one test request to check the address and the key. If the address or the key is wrong, you'll see the error at login, not later when you run your first command. Pass --no-verify to skip this check.

In a script, pass the key with a flag or read it from stdin. Reading from stdin keeps the key out of your shell history and the process list:

mixpost auth login --personal-key <personal-key>
echo "$MIXPOST_PERSONAL_KEY" | mixpost auth login --personal-key-stdin

Flag	Meaning
--url	self-hosted Mixpost address (default: Mixpost Cloud)
--personal-key	the personal key
--personal-key-stdin	read the key from stdin
--workspace	default workspace UUID for this profile
--profile	profile to write (default: the active profile)
--no-verify	save without checking that the address and the key work

Check what's set up and that it works:

mixpost auth status          # the active profile
mixpost auth status --all    # every profile

Remove a profile and the key stored in it:

mixpost auth logout --profile staging

tip

Removing a profile only deletes the copy of the key stored on your computer. The key itself still works until you delete it on the API page in Mixpost.

Self-hosted instances

Without --url, the CLI connects to Mixpost Cloud. For a self-hosted Pro or Enterprise instance, pass the address you open Mixpost at, including its core path:

mixpost auth login --url https://example.com/mixpost

The core path is the value of MIXPOST_CORE_PATH. In Pro v7 and Enterprise v8 it is empty by default, so Mixpost is served from the root of your domain and the address is just https://example.com. If your instance sets it, for example to mixpost, include it: https://example.com/mixpost.

The CLI cleans up the address for you, so all of these work the same way:

example.com/mixpost             https://example.com/mixpost
https://example.com/mixpost/    https://example.com/mixpost/api

• If you leave out the scheme, the CLI uses https://.
• A trailing / or /api is removed.
• If the address has no path, the CLI first tries the default /mixpost core path, then the site root. This means an instance with an empty MIXPOST_CORE_PATH is still found.

If your instance uses a self-signed certificate, add --insecure (or set MIXPOST_INSECURE=true) to skip TLS verification. Only do this on a network you trust.

API access must be enabled

The API is turned on by default. If the CLI can't connect to an instance that is otherwise reachable, check that MIXPOST_API_ACCESS_TOKENS is not set to false in the environment variables.

Choose a workspace

Every command except auth, config, workspace, ping and version works on a single workspace. One key can access every workspace you belong to, so tell the CLI which one to use.

List the workspaces your key can access:

mixpost workspace list

Save one as the profile's default:

mixpost config set workspace 3bbd0951-5b04-432b-b2a0-688588b0720e

Or pick one for a single command with -w. It accepts a workspace UUID, a workspace name or a numeric id:

mixpost post list -w acme
mixpost post list -w 3bbd0951-5b04-432b-b2a0-688588b0720e

A name costs one extra request to look up. A UUID doesn't.

Why there's no MIXPOST_WORKSPACE

You can set the address and the key as environment variables, but not the workspace. This is intentional.

The address and the key say who you are. The workspace says which data you're changing. If you use the wrong address or key, the command fails with 404 or 401. If you use the wrong workspace, the command succeeds and changes the wrong data. An environment variable you set in one terminal and forgot about would make this command dangerous:

mixpost post delete <uuid> --permanent --yes   # in which workspace?

So the workspace only comes from places you set on purpose: the profile (which you can check with mixpost config list) or -w on the command itself.

Profiles

Use profiles to work with more than one instance or account. Create a new one by naming it at login:

mixpost auth login --url https://staging.example.com/mixpost --profile staging

Use a profile for one command, or make it the default:

mixpost post list --profile staging      # this command only
mixpost config use staging               # every command from now on

The first profile you create becomes the default.

Command	Purpose
mixpost config list	list your profiles
mixpost config use <profile>	make a profile the default
mixpost config get <url|personal-key|workspace>	print one setting of the active profile
mixpost config set <url|personal-key|workspace> <value>	change one setting (--profile for another one)
mixpost config path	print where the configuration file is

The configuration file

Profiles are saved in ~/.config/mixpost/config.yml (or $XDG_CONFIG_HOME/mixpost/config.yml). The file is readable only by your user, because it contains your keys:

current_profile: production
profiles:
  production:
    url: https://example.com/mixpost
    personal_key: '...'
    workspace: 3bbd0951-5b04-432b-b2a0-688588b0720e
  staging:
    url: https://staging.example.com/mixpost
    personal_key: '...'

Set MIXPOST_CONFIG to use a different file.

Environment variables

Each setting is taken from the first place it's found, in this order: flag, then environment variable, then profile.

Variable	Flag	Meaning
MIXPOST_URL	--url	self-hosted Mixpost address, including the core path (default: Cloud)
MIXPOST_PERSONAL_KEY	--personal-key	personal key
MIXPOST_PROFILE	--profile	profile to use
MIXPOST_CONFIG		path to the configuration file
MIXPOST_OUTPUT	-o, --output	default output format
MIXPOST_INSECURE	--insecure	skip TLS certificate verification

In CI and containers you often don't need a configuration file. Set MIXPOST_PERSONAL_KEY (and MIXPOST_URL for a self-hosted instance) and pass the workspace with -w. See Scripting and automation.

Permissions

The CLI can do what your user can do in each workspace. Users with the Viewer role can read posts, media and analytics, but can't create, change or delete anything. Write commands fail with exit code 4 (forbidden). Ask a workspace admin for the Member or Admin role if you need to make changes.