Skip to content

cli.rst

Latest commit

 

History

History
213 lines (141 loc) · 5.8 KB

cli.rst

File metadata and controls

213 lines (141 loc) · 5.8 KB
Raw

CLI

The package ships with a command-line entry point named gitcode-api and also supports module invocation via python -m gitcode_api.

The CLI mirrors the synchronous GitCode client surface:

gitcode-api <resource> <method> [options]

For example, client.repos.get() becomes gitcode-api repos get ... and client.pulls.list() becomes gitcode-api pulls list ....

Running gitcode-api with no arguments prints a short banner (version line and ASCII art when stdout is a TTY) followed by the same top-level help as gitcode-api -h.

Installation

Install the package from PyPI:

pip install -U gitcode-api

Or install the local project in editable mode while developing:

pip install -e .

Authentication and connection options

Pass --api-key directly or set GITCODE_ACCESS_TOKEN in your environment. Most leaf commands share --base-url, --timeout, --output-file, --compact, and -e / --escape (see :ref:`cli-escaping`).

The CLI does not expose the Python client's decrypt or custom http_client hooks. If you store an encrypted token or need a bespoke httpx client, use :class:`~gitcode_api.GitCode` in code instead (see :doc:`index` authentication examples).

export GITCODE_ACCESS_TOKEN="your-token"
gitcode-api repos get --owner SushiNinja --repo GitCode-API

If a command calls a repository-scoped method and no owner / repo is available from the command line, the SDK raises GitCodeConfigurationError.

Bundled MCP server (serve)

With the [mcp] extra installed (Python 3.10+), gitcode-api serve starts the bundled FastMCP server (same tool as :doc:`llm_tools`).

  • --transport — stdio, http, or sse (default stdio).
  • --show-banner — true or false to show or hide the FastMCP startup banner; omit the flag to use FastMCP’s default.
  • --owner / --repo — optional defaults for repository-scoped tool calls.
gitcode-api serve --api-key "$GITCODE_ACCESS_TOKEN"

Discovering commands

Use -h / --help at any level to inspect available resource groups, methods, and flags:

gitcode-api --help
gitcode-api repos --help
gitcode-api pulls create --help

Resource help lists subcommand names in the same order as resource.methods on the sync client. Each method's help opens with a signature line matching resource.method_signature("<name>") in Python, then the docstring summary—so the CLI stays aligned with runtime introspection on :class:`~gitcode_api.GitCode`.

Print the installed package version:

gitcode-api --version

Basic examples

Get repository metadata:

gitcode-api repos get \
    --api-key "$GITCODE_ACCESS_TOKEN" \
    --owner SushiNinja \
    --repo GitCode-API

List open pull requests:

gitcode-api pulls list \
    --owner SushiNinja \
    --repo GitCode-API \
    --state open \
    --per-page 20

Search repositories:

gitcode-api search repositories \
    --q sdk

Build an OAuth authorization URL:

gitcode-api oauth build-authorize-url \
    --client-id client-id \
    --redirect-uri https://example.com/callback \
    --scope user_info \
    --state opaque-state

Passing extra keyword arguments

Some SDK methods are not well documented, so the CLI cannot know every supported flag ahead of time. For those methods, pass repeated --set key=value pairs or a JSON object with --set-json.

gitcode-api pulls list \
    --owner SushiNinja \
    --repo GitCode-API \
    --set only_count=true \
    --set reviewer=octocat
gitcode-api repos update \
    --owner SushiNinja \
    --repo GitCode-API \
    --set-json '{"description": "Updated from CLI", "has_wiki": false}'

If the JSON payload is easier to keep in a file, prefix the path with @:

gitcode-api repos update \
    --owner SushiNinja \
    --repo GitCode-API \
    --set-json @payload.json

Output handling

Most commands print JSON to stdout. Use --compact for single-line JSON, or --output-file to write the response to disk.

gitcode-api search repositories --q sdk --compact

Raw-byte responses such as contents get-raw can also be written directly to a file:

gitcode-api contents get-raw \
    --owner SushiNinja \
    --repo GitCode-API \
    --path README.md \
    --output-file README.downloaded.md

Escaping and multi-line input

When using string arguments with escape sequences (such as a line break as \n), your shell may leave the backslashes as literal characters instead of turning them into the intended character. Pass -e / --escape with the sequences you want un-escaped—for example -e '\n\t'. Those tokens are substituted into other string arguments and into string elements of list arguments. The escape flag itself, resource, method, api_key, and base_url are not rewritten. If --escape is set but contains no valid tokens, argument parsing fails.

gitcode-api pulls create ... --body 'Line1\nLine2' -e '\n'

Module invocation

If you prefer not to rely on the installed console script, use the module entry point:

python -m gitcode_api users me --api-key "$GITCODE_ACCESS_TOKEN"