GitLabgitlab-org
cli
main
1package orbit
3import (
4 "context"
5 "errors"
7 "github.com/MakeNowJust/heredoc/v2"
8 "github.com/spf13/cobra"
10 "gitlab.com/gitlab-org/cli/internal/binarymgr"
11 "gitlab.com/gitlab-org/cli/internal/binarymgr/binaries"
12 "gitlab.com/gitlab-org/cli/internal/cmdutils"
13 orbitUpdateCmd "gitlab.com/gitlab-org/cli/internal/commands/orbit/update"
14 "gitlab.com/gitlab-org/cli/internal/config"
15 "gitlab.com/gitlab-org/cli/internal/dbg"
16 "gitlab.com/gitlab-org/cli/internal/iostreams"
17 "gitlab.com/gitlab-org/cli/internal/mcpannotations"
18 "gitlab.com/gitlab-org/cli/internal/text"
19)
21type options struct {
22 io *iostreams.IOStreams
23 cfg config.Config
24 factory cmdutils.Factory
25 execute func(ctx context.Context, io *iostreams.IOStreams, binaryPath string, args, extraEnv []string) error
26 flags binarymgr.Flags
27}
29func NewCmd(f cmdutils.Factory) *cobra.Command {
30 opts := &options{io: f.IO(), cfg: f.Config(), factory: f, execute: executeOrbit}
31 cmd := &cobra.Command{
32 Use: "orbit [<command>] [flags]",
33 Short: `Query the GitLab Orbit context graph. (EXPERIMENTAL)`,
34 Long: heredoc.Docf(`
35 Run the GitLab Orbit CLI through glab.
37 Coding agents: run %[1]sglab orbit --yes skills get orbit%[1]s to load the Orbit skill. %[1]s--yes%[1]s installs the binary without a prompt on first use.
39 Every command and flag, including %[1]s--help%[1]s, is forwarded verbatim to the managed Orbit binary. glab downloads, verifies, and updates that binary for you on first use. Until the binary is installed, %[1]sglab orbit%[1]s and %[1]s--help%[1]s print install instructions instead. glab passes your resolved GitLab credential to the binary on every invocation, so remote commands such as %[1]sglab orbit query%[1]s need no separate login.
41 glab handles only the %[1]supdate%[1]s command and the %[1]s--install%[1]s, %[1]s--update%[1]s, and %[1]s--yes%[1]s flags itself. Run %[1]sglab help orbit%[1]s to see them.
43 Prerequisites:
45 - Run %[1]sglab auth login%[1]s to authenticate.
46 - Orbit must be enabled for your namespace (the %[1]sknowledge_graph%[1]s feature flag).
48 Configuration options:
50 - %[1]sorbit_cli_auto_run%[1]s: Skip the run confirmation prompt.
51 - %[1]sorbit_cli_auto_download%[1]s: Skip the download confirmation prompt.
53 For more information, see the [Orbit documentation](https://docs.gitlab.com/orbit/).
54 `, "`") + text.ExperimentalString,
55 Annotations: map[string]string{
56 mcpannotations.Exclude: "true",
57 "help:environment": heredoc.Docf(`
58 - %[1]sGLAB_ORBIT_CLI_BINARY_PATH%[1]s: Use a local binary instead of the managed one. Skips
59 download, version checks, and updates. Can also be set via the %[1]sorbit_cli_binary_path%[1]s
60 configuration key.
61 - %[1]sORBIT_CLI_AUTO_DOWNLOAD%[1]s: Set to %[1]strue%[1]s to download the binary without a
62 prompt. Required to run in a non-interactive environment such as CI.
63 - %[1]sORBIT_CLI_AUTO_RUN%[1]s: Set to %[1]strue%[1]s to run the binary without a prompt.
64 Required to run in a non-interactive environment such as CI.
65 `, "`"),
66 },
67 Example: heredoc.Doc(`
68 # Install the managed binary without running it, or update it
69 $ glab orbit --install --yes
70 $ glab orbit update
72 # Install on first use without a prompt, then load the Orbit skill
73 $ glab orbit --yes skills get orbit
75 # Show the Orbit binary's own help
76 $ glab orbit --help`),
77 DisableFlagParsing: true,
78 Args: cobra.ArbitraryArgs,
79 RunE: func(cmd *cobra.Command, args []string) error {
80 opts.complete(args)
81 if err := opts.validate(); err != nil {
82 return err
83 }
84 return opts.run(cmd.Context())
85 },
86 }
88 // Registered for `glab help orbit` and the docs; DisableFlagParsing routes real parsing through binarymgr.SplitFlags.
89 fl := cmd.Flags()
90 fl.BoolP("help", "h", false, "Show the Orbit binary's help, or install instructions until the binary is installed.")
91 fl.BoolP("yes", "y", false, "Skip confirmation prompts.")
92 fl.Bool("install", false, "Install the Orbit binary without running it.")
93 fl.Bool("update", false, "Check for and install updates to the binary. Same as the update command.")
95 cmd.AddCommand(orbitUpdateCmd.NewCmd(f))
97 return cmd
98}
100func (o *options) complete(args []string) {
101 o.flags = binarymgr.SplitFlags(args)
102}
104func (o *options) validate() error {
105 if o.flags.Install && o.flags.Update {
106 return errors.New("the --install and --update flags are mutually exclusive")
107 }
108 if (o.flags.Install || o.flags.Update) && len(o.flags.Forwarded) > 0 {
109 return errors.New("the --install and --update flags cannot be combined with a command")
110 }
111 return nil
112}
114func (o *options) run(ctx context.Context) error {
115 if o.flags.HelpOnly() {
116 return o.runHelp(ctx)
117 }
118 runner := binarymgr.NewRunner(o.io, o.cfg, binaries.Orbit())
119 runner.Yes = o.flags.Yes
120 runner.Install = o.flags.Install
121 runner.Update = o.flags.Update
122 runner.Args = o.flags.Forwarded
123 runner.Executor = o.exec
124 if runner.Install {
125 return runner.HandleInstall(ctx)
126 }
127 return runner.Run(ctx)
128}
130func (o *options) runHelp(ctx context.Context) error {
131 spec := binaries.Orbit()
132 status, err := binarymgr.InstalledBinary(o.cfg, spec)
133 if err != nil {
134 dbg.Debugf("orbit help: %v", err)
135 }
136 if status.Installed {
137 return o.exec(ctx, status.Path, o.flags.Forwarded)
138 }
139 managedPath, _ := binarymgr.ManagedBinaryPath(spec)
140 if status.Path != "" && status.Path != managedPath {
141 o.io.LogInfof("The configured %s path %q was not found or is not executable. Fix or unset %s or the %s configuration key.\n", spec.DisplayName, status.Path, "GLAB_ORBIT_CLI_BINARY_PATH", "orbit_cli_binary_path")
142 return nil
143 }
144 o.io.LogInfof(heredoc.Doc(`
145 The %[1]s is not installed.
147 Install it with one of:
148 glab orbit --install --yes Install the binary without running it.
149 glab orbit --yes <command> Install it on first use, then run the command.
151 Run 'glab help orbit' for the flags glab handles itself.
152 `), spec.DisplayName)
153 return nil
154}
156func (o *options) exec(ctx context.Context, binaryPath string, args []string) error {
157 return o.execute(ctx, o.io, binaryPath, args, orbitCredentialEnv(ctx, o.factory))
158}
Diagnostics7 git calls · 218 ms
CallStatusSizeTime0218 ms
discover200185 B3 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=3 git.response.bytes=185 git.server.agent=git/2.56.g1891de4-Linux git.server.object_format=sha1 git.server.caps=agent ls-refs fetch server-option object-format git.server.fetch=shallow wait-for-done filter git.protocol.version=2 git.pkt.frames=9 git.pkt.data=7 git.pkt.flush=2 git.pkt.delim=0 git.pkt.bytes=185 git.pkt.payload.max=35
ls-refs20058 KiB2 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=59849 git.response.cache=UPDATING git.response.duration_ms=2 git.protocol.version=2 git.pkt.frames=731 git.pkt.data=730 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=59849 git.pkt.payload.max=143 git.ls_refs.count=730 git.ls_refs.head=refs/heads/main
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=4273 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=combine:blob:none+tree:2 git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9 git.fetch.haves.count=0 git.fetch.deepen=1 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=7 git.pkt.data=5 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=4273 git.pkt.payload.max=4173 git.sideband.band1.bytes=4173 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=11 git.pack.bytes=4173 git.fetch.wide.objects=11 git.fetch.wide.extra_bytes=3930 git.fetch.wide.blobs=0
fetchtree:0 · deepen 1020032 KiB · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=32926 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=tree:0 git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9 git.fetch.haves.count=0 git.fetch.deepen=10 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=22 git.pkt.data=20 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=32926 git.pkt.payload.max=32046 git.sideband.band1.bytes=32046 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=80 git.pack.bytes=32046 git.pack.ofs_delta=36 git.pack.ref_delta=0 git.pack.chain.max=2 git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91 git.pack.full=44Open pack map
fetchtree:02001.8 KiB · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=4 git.response.bytes=1857 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=tree:0 git.fetch.wants=dce174ff8c632a19d17eea99c8a9b7c37fb2b592 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=1857 git.pkt.payload.max=1830 git.sideband.band1.bytes=1830 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=1830 git.pack.trailer=fb03183b7909876778f740d196d7516811003517Open pack map
fetchtree:0200352 B · hit4 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=207 git.response.bytes=352 git.response.cache=HIT git.response.duration_ms=4 git.fetch.filter=tree:0 git.fetch.wants=60b25b923f1eb09ba37bc303fcc6997e8c86e24f git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=352 git.pkt.payload.max=325 git.sideband.band1.bytes=325 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=325 git.pack.trailer=42eb8867905de3be627920ec4bcafefa8fa8d088Open pack map
fetch2002.3 KiB207 ms
git.upload-pack fetch http.response.status_code=200 git.response.bytes=2309 git.response.cache=MISS git.response.duration_ms=207 git.fetch.wants=708a1a766a30410e4a2970f54f45041b5cb411ca git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=2309 git.pkt.payload.max=2282 git.sideband.band1.bytes=2282 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0
Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.
- Remote
- https://gitlab.com/gitlab-org/cli
- Ref
- refs/heads/main
- Commit
- 0dd7574dce9e385c5c30540e6c15657adc6bdce9
- cf-ray
- a5e231048f46a594
- Request
- ee9fe509…
- Protocol
- v2 · sha1
- Agent
- git/2.56.g1891de4-Linux
- Filter
- advertised
- Fetch
- shallow wait-for-done filter
- Capabilities
- agent ls-refs fetch server-option object-format