CLI

Notra publishes the CLI on npm as notra, and it installs a notra binary that wraps the public API through the official TypeScript SDK so you can script your workspace. It covers posts, brand identities, integrations, schedules and all of GEO: projects, prompts, competitors, scans, visibility, content briefs, agent readiness and AI traffic. Source: github.com/usenotra/notra-cli.

Install

npm install -g notra

yarn global add notra

pnpm add -g notra

bun add -g notra

You can also run any command without installing using npx notra <command> or bunx notra <command>. Verify the install:

notra --version

Authentication

There are two ways to authenticate. Use the browser login when a person is at the keyboard, and an API key when the CLI runs unattended.

notra auth login

This starts an OAuth device authorization flow, in which the CLI prints a short verification code, opens the Notra sign-in page in your browser and waits until you approve the code. The CLI saves access and refresh tokens to the local config file and refreshes them on its own, so you never copy tokens by hand. The session acts as you, inside the organization you pick during sign-in. Notra checks every request against the permissions attached to that session, the same way it checks API requests against key scopes.

On a remote machine or inside a container, use notra auth login --no-browser to print the verification URL instead of opening a browser.

For scripts that drive the login themselves, notra auth login --json streams newline-delimited JSON with one object per line. The first is a pending event with the verification URL and code, followed by either a ready event or an error event. Sign out and remove the stored tokens:

notra auth logout

Use an API key (headless and CI)

An API key bypasses the login entirely. Create one under API Keys in the dashboard with the scopes the job needs (see Authentication), then pass it in one of three ways:

# Environment variable (recommended for CI)
NOTRA_API_KEY=ntra_xxx notra posts list

# Stored in the local config
notra config set api-key ntra_xxx

# Per command
notra posts list --api-key ntra_xxx

notra init does the same thing interactively, prompting for the key or accepting --api-key directly.

notra init
notra init --api-key ntra_xxx

A key only carries the scopes you selected when you created it, so commands that need a scope the key does not have fail with exit code 3.

Configuration

The local config file lives at the OS-standard config path, which on macOS is ~/Library/Preferences/notra-cli-nodejs/config.json, and the CLI creates it with owner-only permissions.

notra config path
notra config get
notra config get api-key
notra config set api-key ntra_xxx
notra config set base-url https://api.usenotra.com

The config keys are api-key and base-url, and environment variables override stored values:

Variable	Default	Purpose
`NOTRA_API_KEY`	none	API key for requests. Bypasses `auth login`.
`NOTRA_BASE_URL`	`https://api.usenotra.com`	API base URL.

Output

Commands print formatted tables in a terminal and switch to JSON when you redirect or pipe stdout, but explicit output flags override that choice. --json always prints JSON, and notra posts get <postId> --markdown always prints Markdown.

notra posts list --status draft --json | jq -r '.posts[].id'
notra posts get post_abc123 --markdown > post.md

Quickstart

notra auth login
notra integrations github --owner usenotra --repo notra
notra brands generate --website-url https://usenotra.com --wait
notra posts generate --content-type changelog --lookback last_7_days --wait
notra posts list --status draft --limit 10
notra geo projects list

Run notra <topic> --help to see every command and flag for a topic.

Posts

Command	Description
`notra posts list`	List posts in the current organization
`notra posts get <postId>`	Fetch a single post (`--markdown` prints only the body)
`notra posts generate`	Queue an async post-generation job
`notra posts status <jobId>`	Read the status of a generation job (`--watch` polls)
`notra posts update <postId>`	Update title, slug, markdown or status
`notra posts delete <postId>`	Delete a post (`--yes` skips the confirmation)

List with filters

notra posts list --status draft --limit 10
notra posts list --content-type changelog,blog_post --sort desc
notra posts list --brand brand_abc --page 2 --json

--status and --content-type accept comma-separated lists, and --sort is asc or desc by creation date.

Generate content

notra posts generate \
  --content-type changelog \
  --brand brand_abc \
  --github-integration integration_xyz \
  --lookback last_7_days \
  --wait

--content-type is one of changelog, blog_post, linkedin_post or twitter_post. --lookback is one of current_day, yesterday, last_7_days, last_14_days or last_30_days. --github-integration and --linear-integration are repeatable. --wait polls until the job finishes (--poll-interval seconds, --timeout-mins minutes), and if you drop it you get the jobId back immediately and can check later with notra posts status <jobId> --watch.

Update content

notra posts update post_abc123 --title "New title" --status published
notra posts update post_abc123 --markdown-file ./post.md
cat post.md | notra posts update post_abc123 --markdown-file -

--status is draft or published.

Delete

notra posts delete post_abc123 --yes

Brand identities

Command	Description
`notra brands list`	List brand identities
`notra brands get <brandIdentityId>`	Fetch a single brand identity
`notra brands generate`	Queue an async brand-identity generation from a website URL
`notra brands status <jobId>`	Read the status of a brand-identity generation job (`--watch` polls)
`notra brands update <brandIdentityId>`	Update name, website, company details, tone, audience, language, instructions or the default flag
`notra brands delete <brandIdentityId>`	Delete a non-default brand identity

Generate from a website

notra brands generate --website-url https://acme.com --name Acme --wait

Update settings

notra brands update brand_abc --tone Professional
notra brands update brand_abc --custom-instructions "Always include PR links"
notra brands update brand_abc --audience "Developers evaluating CI tools"
notra brands update brand_abc --default

The tone options are Conversational, Professional, Casual and Formal, or you can pass --custom-tone for a free-text tone instead. --company-name and --company-description accept an empty string to clear the value.

Integrations

Command	Description
`notra integrations list`	List GitHub, Linear and Slack integrations
`notra integrations github`	Connect a GitHub repository
`notra integrations remove <integrationId>`	Disconnect a GitHub or Linear integration

Connect a repository

notra integrations github --owner usenotra --repo notra
notra integrations github --owner acme --repo website --branch develop
notra integrations github --owner acme --repo private-app --token ghp_xxx

--branch defaults to the repository’s default branch, and you only need a token for private repositories that do not have the Notra GitHub App installed.

Schedules

Manage the cron-based schedules described in Scheduled Automation.

Command	Description
`notra schedules list`	List schedules (`--repo repo_a,repo_b` filters by repository)
`notra schedules create`	Create a schedule from flags or a JSON file
`notra schedules update <scheduleId>`	Replace a schedule with a full JSON body
`notra schedules delete <scheduleId>`	Delete a schedule

Create a schedule

notra schedules create \
  --name "Daily changelog" \
  --frequency daily --hour 9 --minute 0 \
  --output-type changelog \
  --repository repo_abc \
  --lookback yesterday \
  --enabled

For weekly schedules, pass --day-of-week (0-6, Sunday is 0), and for monthly schedules, pass --day-of-month (1-31). --output-type is one of changelog, blog_post, linkedin_post or twitter_post. The CLI can’t create image schedules yet, so create those in the dashboard or through POST /v1/schedules. --repository is repeatable, and you can add --brand-voice <brandIdentityId> to pin a brand identity and --auto-publish to publish changelogs and blog posts instead of saving drafts. All times are in UTC.

From a JSON file

notra schedules create --config-file ./schedule.json
cat schedule.json | notra schedules create --config-file -
notra schedules update sched_abc --config-file ./schedule.json

The JSON body matches the POST /v1/schedules request shape. When you set --config-file, the CLI ignores all other flags.

GEO

GEO commands work on a single project, so run notra geo projects list first to find the project ID and pass it as the first argument to the other commands. Project-scoped commands need a plan that includes GEO.

Topic	Commands
`notra geo projects`	`list`, `get <projectId>`, `create --name <name> [--brand-settings-id <id>]`, `update <projectId>`, `delete <projectId>`
`notra geo settings`	`get <projectId>`, `update <projectId> --config-file <file>` (replaces the whole settings document)
`notra geo prompts`	`list <projectId>`, `create <projectId> --prompt <text>`, `update <projectId> <promptId> --enabled` or `--no-enabled`, `delete <projectId> <promptId>`, `import <projectId> --config-file <json or csv>`
`notra geo sequences`	`list <projectId>`, `create <projectId> --name <name> --step <text>...`, `update <projectId> <sequenceId>`, `run <projectId> <sequenceId>`, `delete <projectId> <sequenceId>`
`notra geo competitors`	`list <projectId>`, `upsert <projectId> --name <name> [--domain ...] [--kind direct or indirect]`, `suggestions <projectId> --domain <domain>`, `import <projectId> --config-file <file>`, `delete <projectId> <name>`
`notra geo scans`	`start <projectId> [--wait]`, `list <projectId> [--page] [--limit]`, `get <projectId> <scanId>`
`notra geo visibility`	`overview <projectId>`, `timeseries <projectId>`, `prompt-results <projectId>`, `competitor-share <projectId>`, `competitor <projectId> <brand>`, `language-share <projectId>` (all accept `--days` or `--from` and `--to`)
`notra geo gaps`	`list <projectId>`
`notra geo briefs`	`list <projectId>`, `get <projectId> <briefId>`, `create <projectId> --topic <text> [--auto-approve]`, `approve <projectId> <briefId>`
`notra geo agent-readiness`	`get <projectId>`, `scan <projectId>`
`notra geo traffic`	`overview <projectId>`, `log <projectId>`, `journeys <projectId>`, `journey <projectId> <journeyId>`, `pages <projectId>`. The ingest commands are organization-level and take no positional project ID: `setup`, `token [--project <projectId>] [--show-token]`, `rotate-token [--project <projectId>] [-y]`

Examples:

notra geo projects create --name "Acme" --brand-settings-id brand_abc
notra geo prompts create proj_123 --prompt "Which tools lead this category?"
notra geo scans start proj_123 --wait
notra geo visibility overview proj_123 --days 30
notra geo briefs create proj_123 --topic "Acme vs alternatives" --auto-approve
notra geo traffic token --project proj_123 --show-token

Scans, sequence runs and content briefs use billed AI credits. notra geo traffic token and rotate-token print secrets only with --show-token, so treat that output as a secret.

Global flags

These flags work on every command:

Flag	Description
`--json`	Print machine-readable JSON instead of a formatted table
`--api-key <value>`	Override the configured key (or `NOTRA_API_KEY`)
`--base-url <value>`	Override the API base URL (or `NOTRA_BASE_URL`)

Destructive commands (delete, remove, rotate-token) ask for confirmation unless you pass -y or --yes.

Exit codes

Code	Meaning
0	Success
1	Generic failure
2	Usage error (bad flag, missing required argument)
3	Authentication failure (no key or session, 401, 403)
4	Rate limited (429)
5	Not found (404, missing resource)
6	Network failure

Source

The CLI is open source at github.com/usenotra/notra-cli, where you can report issues.

Getting Started

Developer Tools

Guides

Webhooks

Endpoints

Install

Authentication

Use an API key (headless and CI)

Configuration

Output

Quickstart

Posts

List with filters

Generate content

Update content

Delete

Brand identities

Generate from a website

Update settings

Integrations

Connect a repository

Schedules

Create a schedule

From a JSON file

GEO

Global flags

Exit codes

Source

​Install

​Authentication

​Sign in with your browser (recommended)

​Use an API key (headless and CI)

​Configuration

​Output

​Quickstart

​Posts

​List with filters

​Generate content

​Update content

​Delete

​Brand identities

​Generate from a website

​Update settings

​Integrations

​Connect a repository

​Schedules

​Create a schedule

​From a JSON file

​GEO

​Global flags

​Exit codes

​Source

Install

Authentication

Sign in with your browser (recommended)

Use an API key (headless and CI)

Configuration

Output

Quickstart

Posts

List with filters

Generate content

Update content

Delete

Brand identities

Generate from a website

Update settings

Integrations

Connect a repository

Schedules

Create a schedule

From a JSON file

GEO

Global flags

Exit codes

Source