tooig 0.1.3

Interactive framework for tooig developer program

tooig CLI

tooig is the secure setup CLI for Tooig developers. It is published with the same name and version to PyPI and npm. Both distributions implement the same authentication, build authorization, credential-storage, and SDK-installation flow.

Table of contents

1. Requirements
2. Installation
3. Developer setup walkthrough
4. Authentication
5. Build authorization
6. Framework installation
7. Credential storage
8. Configuration
9. Service contract
10. Security model
11. Troubleshooting
12. Release process

Requirements

Use either of these runtimes:

• Python 3.10 or newer and pip.
• Node.js 20 or newer and npm or pnpm.

The selected framework must exist in the same package registry as the installed CLI. The Python CLI installs from PyPI; the Node.js CLI installs from npm.

Installation

Python and pip

python -m pip install --upgrade tooig
tooig developer

npm

Install globally:

npm install --global tooig
tooig developer

Or run without a permanent global installation:

npx tooig developer

pnpm

pnpm add --global tooig
tooig developer

Or:

pnpm dlx tooig developer

npx install --g tooig is not a valid npm installation command. Use npm install --global tooig or npx tooig developer instead.

Developer setup walkthrough

Run:

tooig developer

The CLI performs these steps:

1. Prompts for the name portion of the developer email. Enter ada for [e-mail].
2. Offers Sign in and Create developer account.
3. Reads the password without echoing characters to the terminal.
4. Authenticates with the Tooig API.
5. Offers browser authorization or an existing API key.
6. Validates and stores the resulting API key.
7. Offers nineth and bridge (nineth-bridge).
8. Installs the selected SDK using the CLI's package ecosystem.
9. Prints the getting-started URL: https://developer.tooig.com/get_started.

Use --no-open on remote machines to print the browser authorization URL without launching a browser:

tooig developer --no-open

Authentication

The prompt accepts only the local portion of a Tooig developer address:

email: [name]@developer.tooig.com

The suffix is fixed by the CLI. Local parts are normalized to lowercase and may contain letters, numbers, dots, underscores, and hyphens.

For a new account, select Create developer account and use a password of at least 12 characters. The CLI submits the signup and then authenticates. If the account policy requires email verification, verify the address and run tooig developer again.

Passwords and short-lived login tokens are held in memory only. They are never written to the credential file or displayed in progress/error output.

Build authorization

Secure browser link

The CLI asks the Tooig API to create a signed, short-lived authorization request. The service returns the link; the CLI does not generate or sign authorization links locally.

https://developer.tooig.com/{server-generated-id}

The link is opened in the default browser unless --no-open is set. The CLI polls the service until the request is approved, denied, cancelled, or expired. On approval, the service returns the build API key.

The CLI rejects an authorization URL that changes the configured API host or downgrades HTTPS. Localhost development may use HTTP.

Existing API key

Select Use an existing API key. Input is hidden. Before storing the key, the CLI validates it against the authenticated session endpoint. Invalid or truncated keys are not saved.

Framework installation

The framework choices and commands are:

CLI distribution	Selection	Command
PyPI	nineth	python -m pip install --upgrade nineth
PyPI	bridge	python -m pip install --upgrade nineth-bridge
npm	nineth	npm install nineth
npm	bridge	npm install nineth-bridge
pnpm	nineth	pnpm add nineth
pnpm	bridge	pnpm add nineth-bridge

The Node.js CLI detects pnpm through npm_config_user_agent; all other npm/npx invocations use npm. Installer commands use argument arrays and never interpolate user input into a shell command.

Credential storage

Python and Node.js use the same versioned JSON format so either CLI can reuse the authorization:

Platform	Default location
Windows	%APPDATA%\\tooig\\credentials.json
macOS	~/Library/Application Support/tooig/credentials.json
Linux	${XDG_CONFIG_HOME:-~/.config}/tooig/credentials.json

The file contains the developer email, API base URL, and API key. It never contains the password or login token.

Writes use a temporary file followed by an atomic rename. On POSIX systems the directory is mode 0700 and the file is mode 0600. Both clients refuse to read or replace a symlinked credential file. Do not commit this file or copy it into a project directory.

Configuration

The production API is used by default:

https://developer.tooig.com/api

Override it for development with TOOIG_API_URL or --api-url:

tooig developer --api-url http://localhost:8000/api

Non-local API URLs must use HTTPS and cannot contain embedded usernames or passwords.

Service contract

The CLI expects these server endpoints relative to the API base URL:

Method	Endpoint	Purpose
POST	/auth/signup	Create a developer account.
POST	/auth/login	Return a short-lived access_token.
GET	/auth/session	Validate an existing bearer API key.
POST	/developer/authorizations	Create a signed browser authorization request.
GET	/developer/authorizations/{id}	Poll pending, approved, denied, cancelled, or expired.

The authorization creation response is:

{
  "id": "server-generated-id",
  "authorization_url": "https://developer.tooig.com/server-generated-id",
  "interval": 2,
  "expires_in": 300
}

An approved poll response is:

{
  "status": "approved",
  "api_key": "server-issued-secret"
}

The repository currently supplies /auth/signup, /auth/login, and /auth/session. Browser authorization requires the /developer/authorizations service to be deployed before that option can complete. Existing API-key authorization is usable against the current API.

Security model

• HTTPS is mandatory except for loopback development.
• Password and API-key prompts do not echo input.
• The server signs and issues authorization requests and keys.
• Authorization URLs are origin-checked before opening.
• Login tokens are not persisted.
• Existing keys are validated before persistence.
• Secrets are not passed as command-line arguments to package managers.
• Network failures are converted to bounded errors without response dumps.
• Framework names are selected from a fixed allowlist.
• Credential writes are atomic and symlink-resistant.

Local credential-file protection is not a substitute for full-disk encryption or a locked operating-system account. Rotate the API key immediately if the workstation or file is compromised.

Troubleshooting

Account creation succeeds but login fails

The account may require email verification. Complete verification and rerun tooig developer using Sign in.

Browser authorization is unavailable

Use Use an existing API key until the browser-authorization service is deployed. For remote or headless environments, use --no-open and open the printed link on another trusted device.

Package installation fails

Check registry access and install the selected package directly using the command in Framework installation. The authorization remains stored, so rerunning setup does not expose the password or key.

PowerShell blocks npm.ps1

Use npm.cmd in a restricted PowerShell session or adjust the local execution policy according to your organization's policy. The published tooig executable itself does not require shell interpolation.

Release process

Repository versioning is controlled by the first recognized dispatch token in a commit message:

Dispatch	Version bump	Repository	PyPI/npm tooig
build:	Major	Bump and GitHub release	No publish
feat:	Minor	Bump and GitHub release	No publish
chore:	Patch	Bump and GitHub release	No publish
build[tooig]:	Major	Bump and GitHub release	Bump, build, validate, publish, release
feat[tooig]:	Minor	Bump and GitHub release	Bump, build, validate, publish, release
chore[tooig]:	Patch	Bump and GitHub release	Bump, build, validate, publish, release

The PyPI and npm versions must match before a scoped release. The script updates both manifests and the npm lockfile together. Repository tags use vX.Y.Z; package tags use tooig-vX.Y.Z.

GitHub Actions requires:

• An npm automation token in the NPM_TOKEN repository secret.
• PyPI Trusted Publishing configured for this repository and workflow.
• contents: write and id-token: write, already declared by the workflow.

The repository release reads .github/release_notes/repository.md. The package release reads .github/release_notes/tooig.md.