Antwork CLI

The Antwork CLI is a small command-line client for the same MCP server your AI assistant talks to. It is for the times you want a terminal instead of a chat window: piping a draft out of a file, checking your quota before a launch, or wiring Antwork into a shell script you already have.

Status

Early. login, whoami, tools and the raw tool passthrough work today. The shorthand verbs for posting and scheduling are next. Until version 1.0 the flag surface may change.

What it is not

• ›Not a replacement for the AI integration — drafting in your own voice still works best through an assistant that can read your voice profile.
• ›Not usable in CI or cron. See Automation below for why, and what would have to change.
• ›Not a way to avoid signing in. There are no API keys.

Node 20.9 or newer. The package has no runtime dependencies, so nothing else is pulled in.

Not on npm yet

Build from source

git clone https://github.com/iker-gonzalez/antwork.io.git
cd antwork.io && npm ci
npm run cli:build
cd packages/cli && npm link

dist/ is not committed, so build once after cloning. npm link then puts a real antwork command on your PATH, exactly as a published install would.

Once published

npm install -g antwork

Verify

antwork --version

If antwork is not found after installing, your npm global bin directory is not on PATH. npm prefix -g prints where it went.

1. Sign in

antwork login

This opens your browser. Approve the request and the terminal continues on its own — there is no code to copy back.

2. Confirm it worked

antwork whoami

You should see your plan, your workspace and how much of your posting quota this cycle has used.

3. Look around

antwork tools

Every tool the MCP server exposes is reachable from the CLI, whether or not it has a shorthand yet.

Global flags: --json for machine-readable output, plus --version and --help.

Output and exit codes

Data goes to stdout, everything else to stderr, so antwork whoami --json | jq always works. Exit codes are part of the contract:

• ›0 — success
• ›1 — the operation failed (quota reached, account disconnected, bad id)
• ›2 — you used it wrong (unknown flag, malformed key=value)

The server exposes about forty tools and the CLI only gives shorthand to the common ones. antwork tool reaches the rest, so nothing is ever locked away behind a missing subcommand.

antwork tool list_posts status=draft limit=20
antwork tool get_post_context platform=linkedin
antwork tool attach_media post_id=abc123 media_urls=@media.json

How values are typed

Values are typed by shape rather than guessed from a schema:

• ›true, false and null become those literals.
• ›Plain integers become numbers — but only when the round trip is lossless, so an id like 0123 stays a string.
• ›Values starting with [ or { are parsed as JSON, falling back to a string if that fails.
• ›@file.json is read from disk and parsed. Use it for the arguments that resist flags.
• ›Anything else stays a string.

Prefix a value with a backslash to force it to a string: text=\true and handle=\@antwork.

antwork login runs the standard OAuth flow for native apps. The CLI opens a listener on your own machine, registers itself, sends you to Antwork in a browser, and exchanges the returned code using PKCE. No password ever reaches the CLI, and there is nothing to copy and paste.

Where credentials live

A refresh token — not a password — is written to ~/.antwork/credentials.json with file mode 0600.

Treat that file like a password

How long sign-in lasts

Access tokens last five minutes and refresh automatically. The refresh token lasts thirty days and renews every time it is used, so a CLI you touch weekly never asks you to sign in again. Leave it a month and it will.

On a remote box or inside a dev container the browser runs on your laptop, but the sign-in callback goes to the remote machine — so the normal flow cannot finish. Pin the port and forward it:

ssh -L 51337:127.0.0.1:51337 your-host
ANTWORK_CALLBACK_PORT=51337 antwork login

Any free port works, as long as the same number is used in both commands.

The CLI does not work unattended, and this is a property of the server rather than an omission here.

Antwork's authorization server offers only the authorization-code and refresh-token grants. There is no device-code flow, no client-credentials grant and no API keys, so every first sign-in needs a human at a browser.

Do not put a refresh token in CI

"Not signed in" straight after signing in

The credentials file is written on sign-in; if ANTWORK_CREDENTIALS is set in one shell and not another, each shell sees a different file. antwork whoami --json reports which server the stored token belongs to.

"Session expired"

The refresh token passed thirty days without use, or it was revoked from your connected-AI settings. Run antwork login again.

The browser opens but the terminal never continues

Something is between the browser and the loopback listener — commonly a remote shell. See Signing in over SSH above.

A tool reports a missing scope

Publishing and media upload need scopes granted at sign-in. If you signed in before those were requested, run antwork login again to re-consent.

"MCP endpoint not found"

If you set ANTWORK_MCP_URL by hand, drop any trailing slash. The server matches the path exactly and a trailing slash produces a 404 that looks like an outage.