@anakonn/ankk

@anakonn/ankk provides the Bun-first ankk command for apps/api-public /v1.

Install

The CLI currently requires Bun.

bunx @anakonn/ankk --json health

Or install globally:

bun install -g @anakonn/ankk
ankk --json health

Upgrade

Global Bun installs can upgrade through the CLI:

ankk upgrade
ankk upgrade --dry-run

The CLI uses the latest npm dist-tag. Release versions use three-part numeric SemVer such as 0.1.1.

Initial Setup

Create a global config after installing the CLI:

ankk config setup --scope global

For a repository or working directory, create a project config:

ankk config setup --scope project

For CI or other non-interactive environments:

ANKK_API_KEY=spk_... ankk config setup --scope global --brand-ref <brand_ref> --api-key-env ANKK_API_KEY --yes

The setup command creates .ankk/ or ~/.ankk/ when needed and writes the config file with owner-only permissions. API key input is visible so pasted keys are easier to verify, but command output and config show never print the full key.

Project config is discovered from the current directory upward. This lets you run brand-scoped commands from nested project folders without repeating --brand-ref.

Runtime config precedence for credentials and brand context is:

1. CLI flags such as --api-key, --brand-ref, and --config
2. ANKK_API_KEY for the API key
3. Project config: .ankk/config.json
4. Global config: ~/.ankk/config.json
5. ANKK_BRAND_REF for the default brand reference

base_url is a development and smoke-test override. Most users should leave it unset. Use --base-url or ANKK_BASE_URL when testing preview or local API targets. If no override is present, the CLI uses https://api-public.ankk.app.

Inspect the resolved config without exposing the full key:

ankk config show

SNS Content

Use content for Ankk-managed work items: create, schedule, inspect publish state, cancel scheduled content, and delete mutable content.

Use posts for provider posts that already exist on SNS providers. Scheduled content appears in content, not posts. Provider-origin posts may appear in posts even when Ankk did not create them. An Ankk content item appears in posts only after it has provider post identity such as provider_post_id.

Publish immediately from a JSON request body:

ankk content publish --file payload.json

Schedule the same payload with an ISO timestamp:

ankk content publish --file payload.json --scheduled-for 2026-06-18T09:00:00Z

Pass --brand-ref <brand_ref> on any brand-scoped command to override the configured default for one command.

If payload.json also contains scheduled_for, it must match --scheduled-for. Relative inputs such as 10m are not supported yet.

Publish

Public npm publish runs automatically when CLI-related changes reach the repository main branch. Before merging CLI changes to main, update apps/cli/package.json to the release version.

The CI job publish:cli:npm validates that apps/cli/package.json uses three-part numeric SemVer, that the version is not already published, and then publishes with npm dist-tag latest. If the version was already published, the job fails so the missing version bump is visible.

The current repository is hosted on self-managed GitLab. npm Trusted Publishing is preferred, but npm currently documents GitLab support for GitLab.com shared runners. Until this project publishes from a supported runner, use a granular npm token with the smallest practical scope:

• Token name: ankk-cli-publish or similar.
• Package/scope access: @anakonn/ankk only, after the package exists.
• Permission: publish/write access required by npm publish.
• Organization access: none unless npm requires it for the @anakonn scope.
• Expiration: finite.
• GitLab variable: NPM_TOKEN, masked and protected.
• GitLab protected branch: main.

If this is the first ever publish and npm cannot scope a token to an unpublished package, publish @anakonn/ankk once manually with 2FA, then replace CI with a package-scoped token for later publishes.

When publishing moves to a supported Trusted Publishing runner, configure npm Trusted Publisher with:

• Provider: GitLab CI/CD.
• Namespace: anakonn.
• Project name: ankk.
• Top-level CI file path: .gitlab-ci.yml.
• Allowed actions: npm publish.

Then remove NPM_TOKEN from CI and add GitLab id_tokens for NPM_ID_TOKEN with audience npm:registry.npmjs.org.

OpenAPI Generation

The committed OpenAPI snapshot is generated from the local apps/api-public Elysia app, not from production. This lets API and CLI changes ship in the same MR before https://api-public.ankk.app has the new contract.

(cd apps/cli && bun run generate:openapi)
(cd apps/cli && bun run coverage:openapi)

Use live production pull only for dogfooding or deployed-contract comparison:

(cd apps/cli && bun run src/entry/index.ts --json openapi pull --dry-run)

Content Payload Examples

TikTok photo publishing uses provider_settings.tiktok.postMode because TikTok separates Direct Post from upload-to-inbox. Photo URLs must be publicly reachable and allowed by the app's TikTok verified URL prefix/domain.

{
	"connection_id": "<tiktok_connection_id>",
	"idempotency_key": "tiktok-photo-upload-to-inbox-2026-06-17",
	"sns_type": "tiktok",
	"text": "Photo caption",
	"media": [{ "asset_ref": "https://cdn.example.com/photo.jpg" }],
	"provider_settings": {
		"content_type": "photo",
		"tiktok": {
			"postMode": "upload_to_inbox"
		}
	}
}

Smoke

Use environment variables or ~/.ankk/config.json for credentials. Do not paste or commit full spk_ API keys in logs, docs, issue comments, or shell snippets.

bunx turbo run check --filter=@anakonn/ankk
bunx turbo run test --filter=@anakonn/ankk
(cd apps/cli && bun run coverage:openapi)
(cd apps/cli && bun run src/entry/index.ts --json health)
(cd apps/cli && bun run src/entry/index.ts --json openapi pull --dry-run)

Authenticated smoke, when a safe API key is already available in the local environment:

(cd apps/cli && ANKK_API_KEY=... bun run smoke:dogfood)
(cd apps/cli && ANKK_API_KEY=... bun run src/entry/index.ts --json brands list)
(cd apps/cli && ANKK_API_KEY=... bun run src/entry/index.ts --json brands info get --brand-ref <brand_ref>)

Optional patch smoke is disabled by default. To enable it, set both ANKK_BRAND_REF and ANKK_BRAND_INFO_PATCH_FILE. Keep the patch payload under tmp/ and inspect it before running.

(cd apps/cli && ANKK_API_KEY=... ANKK_BRAND_REF=<brand_ref> ANKK_BRAND_INFO_PATCH_FILE=../../tmp/brand-info-patch.json bun run smoke:dogfood)

For write commands, prefer --file path or --file - and keep fixture payloads under the repository tmp/ directory when they are temporary.